[フレーム]

baserCMS Documentation

はじめに

導入

運用

参加・貢献

リソース

GitHubでこのページを編集

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

Index

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

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

リクエストルール

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

フォーマット

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

# ${summary}
${description}
## 実行に必要な権限
 
```
`${roles}`
```
## リクエスト
```
`${method} ${url}`
```
### パスパラメータ
| パラメータ名 | 必須 | 型 | 内容 | サンプル値 |
|------------|-----|----|-----|-----------|
| | | | | |
### クエリパラメータ
| パラメータ名 | 必須 | 型 | 内容 | サンプル値 |
|------------|-----|----|-----|-----------|
| | | | | |
### リクエストボディ
| パラメータ名 | 必須 | 型 | 内容 | サンプル値 |
|------------|-----|----|-----|-----------|
| | | | | |
## レスポンス例
### レスポンスボディ
```json
${responseBodyExample}
```

AltStyle によって変換されたページ (->オリジナル) /