Dev Docs

Appearance

OpenAPI YAML Style Guidelines ​

エンドポイントに tags を使う ​

関連エンドポイントをグループ化するために tags を使用します。

yaml
tags:
  - name: articles
    description: Articles 関連のエンドポイント

各エンドポイントに operationId を設定する ​

operationId を {動詞}{リソース} の形式で指定し、一意に識別します。

yaml
operationId: getArticle
operationId: createArticle
operationId: listArticles

レスポンスに API バージョンを含める ​

レスポンスボディは data キーの下にネストし、apiVersion を含めます。

json
{
    "apiVersion": "1.0.0",
    "data": {
        "article": {
            "id": "1",
            "title": "Article 1",
            "content": "Content 1"
        }
    }
}

各エンドポイントにリクエスト・レスポンススキーマを定義する ​

yaml
components:
    schemas:
        Article:
            ...
    requests:
        CreateArticleRequest:
            ...
    responses:
        CreateArticleResponse:
            ...

エラーレスポンスに共通スキーマを使う ​

yaml
components:
    schemas:
        Error:
            type: object
            properties:
                code:
                    type: string
                message:
                    type: string
            required:
                - code
                - message
    responses:
        ErrorResponse:
            description: Error response
            content:
                application/json:
                schema:
                    type: object
                    properties:
                    apiVersion:
                        $ref: '#/components/schemas/ApiVersion'
                    error:
                        $ref: '#/components/schemas/Error'
                    required:
                    - apiVersion
                    - error