はじめに

導入

運用

参加・貢献

リソース

GitHubでこのページを編集

Home / 5 / doc_writing / APIドキュメント校正ルール

Index

APIドキュメント校正ルール

APIドキュメントを作成の際は以下のルールに従って作成します。

リクエストルール

  • パスパラメータ、クエリパラメータ、リクエストボディは扱うもののみを記載する
  • パスパラメータ
    • {} でくくる
      • リクエスト e.g. /api/v2/users/{userId}
      • 同じものをパスパラメータに記載する
    • 並び順
      • 必須のものを上
      • 必須、必須ではないもの、それぞれで英字昇順

フォーマット

以下の書式をベースとする。

# ${summary}

${description}

## 実行に必要な権限
    
```
`${roles}`
```

## リクエスト
```
`${method} ${url}`
```

### パスパラメータ

| パラメータ名 | 必須 | 型 | 内容 | サンプル値 |
|------------|-----|----|-----|-----------|
|            |     |    |     |           |

### クエリパラメータ

| パラメータ名 | 必須 | 型 | 内容 | サンプル値 |
|------------|-----|----|-----|-----------|
|            |     |    |     |           |

### リクエストボディ

| パラメータ名 | 必須 | 型 | 内容 | サンプル値 |
|------------|-----|----|-----|-----------|
|            |     |    |     |           |

## レスポンス例

### レスポンスボディ

```json
${responseBodyExample}
```