Documenter l'API REST du backend (docs/API.md)

オープン
#92 コメント 0 件 リアクション 0 件 担当者 0 名 GitHub で見る

まだ誰も着手していません。

評価

難易度
4/5
見積もり時間
3〜5日
初心者へのやさしさ
58/100
issue の種類
ドキュメント
明瞭さ
明確に書かれている
活発さ
静か
技術スタック
go, openapi
領域
api, documentation

調査の方向性

Start with backend/main.go to enumerate registered routes, then inspect backend/api/handler/ and backend/api/service/ for access requirements and exact payload structures. Check the apierror format and invitation flow, then link the finished API reference from the README’s Documentation section. Done means every route, required header and minimum role, mutation example, error format, and end-to-end invitation flow is documented.

索引モデルが issue の本文から書いたものです。

説明

documentation good first issue

Objectif

Produire la documentation complète des endpoints REST exposés par le backend Go. Ce document sert de contrat d'interface entre le frontend et le backend, et de point d'entrée pour toute intégration tierce.

User story

En tant que développeur frontend ou intégrateur, je veux consulter la liste exhaustive des routes, leurs payloads et les en-têtes attendus, afin d'appeler l'API correctement sans lire le code Go.

Tâches

  1. Créer docs/API.md. Une spécification OpenAPI est également acceptable si le contributeur préfère.
  2. Recenser les routes — analyser backend/main.go, où toutes les routes sont enregistrées, et le dossier backend/api/handler/. Couvrir /api/auth/*, /api/bands/*, /api/song/*, /api/setlist/*, /api/interlude/*.
  3. Documenter l'authentification — indiquer clairement, pour chaque route, si elle est publique, si elle exige le token Bearer (JWTAuth), et si elle exige l'en-tête de contexte de groupe X-Band-ID. Signaler les routes protégées par AdminOnly.
  4. Payloads et réponses — pour chaque endpoint, un exemple de corps de requête et la réponse attendue. Les structures exactes se trouvent dans backend/api/service/ (CreateSongPayload, etc.).
  5. Codes d'erreur — documenter le format d'erreur renvoyé par apierror et les codes existants.
  6. Mécanique d'invitation — expliquer le flux d'invitation par token, qui n'est pas évident à la lecture des seules routes.
  7. Lier depuis le README, dans la section Documentation existante.

Critères d'acceptation

  • Toutes les routes enregistrées dans main.go figurent dans le document
  • Chaque endpoint indique sa méthode, son chemin, ses en-têtes requis et son rôle minimum
  • Chaque endpoint de mutation a un exemple de payload JSON
  • Le format des erreurs est documenté
  • Le flux d'invitation est expliqué de bout en bout
  • Le README pointe vers docs/API.md

⚠️ Point de vigilance

Les payloads réels sont définis dans les services, pas dans les handlers. C'est backend/api/service/ qu'il faut lire pour connaître la forme exacte des JSON attendus.

主要言語
Python
スター
2
フォーク
0
平均マージ
21分
マージ済み PR(30日)
2

環境構築

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

Doud75/Setly のほかの issue

Doud75/Setly の issue をすべて見る

似ている issue

Python の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。