LoginSignup
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@taroppu(h goto)

OpenAPI 3.1 YAMLの書き方

Posted at

とにかく分からないので１行ずつ意味を理解していく。

「OpenAPI Specification v3.1.0」を読みながら書いています。

抜けている定義行があるかもしれません。
また、Swagger UIで随時previewしていますが細かい誤りある可能性があります。

分類方法

初見だとOpenAPIの規定値と規定値外で混乱するため以下の３種類に分類

  • 「必須」 (Required)：OpenAPI3.1の予約語。必ず書かなければならない定義
    （ただし、上位インデントが「任意」の場合は記載が不要になることがある）
  • 「任意」(Optional)：OpenAPI3.1の予約語。省略可能な定義
  • 「独自定義」 (Custom-defined)：OpenAPI3.1 YAMLに関係ない任意名の定義

YAML

ルートレベルの例：openapi【string】
openapi: 3.1.0 # 必須: OpenAPIのバージョン【string】
ルートレベルの例：info【Info Object】
info:  # 必須: APIに関する基本情報【Info Object】
  ### 【Info Object】 ###
  title: API名  # 必須: APIのタイトル【string】
  description: 説明  # 任意: APIの説明【string】
  termsOfService: https://example.com/terms/  # 任意: APIの利用規約のURL【string】
  contact:  # 任意: APIに関する連絡先【Contact Object】
    name: 連絡先名  # 任意: 連絡先の名前【string】
    url: https://example.com/contact/  # 任意: 連絡先のURL【string】
    email: aa@aa.ne.jp  # 任意: 連絡先のメールアドレス【string】
  license:  # 任意: APIのライセンス情報【License Object】
    name: ライセンス名  # 必須: ライセンスの名前【string】
    identifier: ライセンス識別子  # 任意: ライセンスの識別子【string】
    url: https://example.com/license/  # 任意: ライセンスのURL【string】
  version: 1.0.0  # 必須: APIのバージョン【string】
ルートレベルの例：jsonSchemaDialect【string】
jsonSchemaDialect: "https://json-schema.org/draft/2020-12/schema"  # 任意: 使用するJSON Schemaのバージョン【string】
ルートレベルの例：servers【[Server Object]】
servers:  # 必須: APIがホストされるサーバーの情報【[Server Object]】
  ### 【Server Object】 ###
  - url: /api/{version}  # 必須: サーバーのURL【string】
    description: 説明  # 任意: URLの説明【string】
    variables:  # 任意: URLの変数を定義（変数定義時に使用）【Map[string, Server Variable Object]】
      ### string(MapのKey)
      version:  # 独自定義: バージョン変数【string】
        ### Server Variable Object(MapのValue) ###
        default: v1  # 必須: 変数のデフォルト値【string】
        description: 変数の説明  # 任意: 変数の説明【string】
ルートレベルの例：paths【Paths Object】
paths:  # 必須: 各エンドポイントのパスとその操作を定義【Paths Object】
  ### 【Paths Object】 ###
  /test/info:  # 独自定義: エンドポイント名【Path Item Object】
    ### 【Path Item Object】 ###
    # $ref: # 任意【string】（割愛）
    summary: 概要  # 任意: エンドポイントの概要【string】
    description: 説明  # 任意: エンドポイントの詳細な説明【string】
    post:  # 必須: HTTPメソッド（get, put, post, delete, options, head, patch, trace, servers）【Operation Object】
      ### 【Operation Object】 ###
      # tags: # 任意【[string]】（割愛）
      summary: 概要  # 任意: エンドポイントの概要【string】
      description: 説明  # 任意: エンドポイントの説明【string】
      # externalDocs: # 任意【External Documentation Object】（割愛） 
      # operationId: # 任意【string】（割愛）
      parameters:  # 任意: エンドポイントのリクエストパラメータ【[Parameter Object | Reference Object]】
        ### 【Parameter Object】 ###
        - name: testId2  # 必須: パラメータの名前【string】
          in: query  # 必須: パラメータの場所（query, header, path, cookie）【string】
          description: パラメータの説明  # 任意: パラメータの説明【string】
          required: true  # 必須 or 任意（inがpathの場合は必須かつtrue、query, header, cookiesの場合は任意【boolean（default値はfalse扱い）】
          ### deprecated: # 任意【boolean】（割愛）
          ### allowEmptyValue: # 任意【boolean】（割愛）
          style: form  # 任意: パラメータのスタイル（matrix, label, form, simple, spaceDelimited, pipeDelimited, deepObject）【string（default値はinの値に応じて変わる）】
          # explode: # 任意【boolean（default値はinの値に応じて変わる）】（割愛）
          # allowReserved: # 任意【boolean（default値はfalse扱い）】（割愛）
          schema:  # 任意: パラメータのスキーマ【Schema Object】
            ### 【Schema Object】 ###
            ### json-schema.orgを参照して記述する ###
            ## https://json-schema.org/draft/2020-12/vocab/core
            ## ⇒ JSON Schemaの基本的な構造やメタデータに関する定義が記載されている。
            ## https://json-schema.org/draft/2020-12/vocab/validation
            ## ⇒ JSON Schemaのバリデーションルールが定義されている。データ型（type）、制約（minimum, maximum, patternなど）、必須プロパティ（required）など、スキーマのバリデーションに関する詳細な情報も記載。
            type: string  # 必須: パラメータのタイプ【string】
            format: uuid  # 任意: パラメータのフォーマット【string】
            minLength: 36  # 任意: パラメータの最小長【integer】
            maxLength: 36  # 任意: パラメータの最大長【integer】
            pattern: '^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$'  # 任意: パラメータの正規表現パターン【string】
            description: UUID形式のパラメータ  # 任意: パラメータの詳細な説明【string】
            example: '123e4567-e89b-12d3-a456-426614174000'  # 任意: パラメータの例【Any】
        - $ref: '#/components/parameters/testId'  # 任意: パラメータの参照【Reference Object】
      requestBody:  # 任意: リクエストボディの定義【Request Body Object | Reference Object】
        ### 【Request Body Object】 ###
        description: 説明  # 任意: リクエストボディの説明【Request Body Object】【string】
        required: true  # 任意: リクエストボディが必須かどうか【boolean（default値はfalse扱い）】
        content:  # 必須: リクエストボディのコンテンツタイプとスキーマ【Map[string, Media Type Object]】
          ### string(MapのKey) ###
          application/json:  # 必須: コンテンツタイプ【string】
            ### 【Media Type Object(MapのValue)】 ###
            schema:  # 任意: スキーマの参照【Schema Object】
              ### 【Schema Object】 ###
              ### json-schema.orgを参照して記述する ###
              ## https://json-schema.org/draft/2020-12/vocab/core
              ## ⇒ JSON Schemaの基本的な構造やメタデータに関する定義が記載されている。
              ## https://json-schema.org/draft/2020-12/vocab/validation
              ## ⇒ JSON Schemaのバリデーションルールが定義されている。データ型（type）、制約（minimum, maximum, patternなど）、必須プロパティ（required）など、スキーマのバリデーションに関する詳細な情報も記載。
              $ref: '#/components/schemas/CustomerInfoRequestBody'  # 必須: スキーマの参照【Reference Object】
            example:  # 任意: リクエストボディのサンプルデータ【any】
              customerId: 'ほげほげ'  # 任意：サンプルデータの顧客ID【string】
            # examples:  # 任意【Map[string, Example Object]】（割愛）
            # encoding: 任意【Map[string, Encoding Object]】（割愛）
        # $ref: # 任意【Refaerence Object】（割愛）
      responses:  # 必須: レスポンスの定義【Map[string, Response Object | Reference Object]】
        ### string(MapのKey) ###
        '200':  # 独自定義: HTTPステータスコード（一つ以上必須）【string】
          ### 【Response Object(MapのValue)】 ###
          description: 情報の取得に成功しました  # 必須: レスポンスの説明【string】
          # headers: # 任意【Map[string, Header Object | Reference Object]】（割愛）
          content:  # 必須: レスポンスのコンテンツタイプとスキーマ【Map[string, Media Type Object]】
            ### string(MapのKey) ###
            application/json:  # 必須: コンテンツタイプ【string】
              ### 【Media Type Object(MapのValue)】 ###
              schema:  # 必須: スキーマの参照【Schema Object】
                ### 【Schema Object】 ###
                ### json-schema.orgを参照して記述する ###
                ## https://json-schema.org/draft/2020-12/vocab/core
                ## ⇒ JSON Schemaの基本的な構造やメタデータに関する定義が記載されている。
                ## https://json-schema.org/draft/2020-12/vocab/validation
                ## ⇒ JSON Schemaのバリデーションルールが定義されている。データ型（type）、制約（minimum, maximum, patternなど）、必須プロパティ（required）など、スキーマのバリデーションに関する詳細な情報も記載。
                $ref: '#/components/schemas/TestAccountInfoResponse'  # 必須: スキーマの参照パス【Reference Object】
              example:  # 任意: レスポンスのサンプルデータ【any】
                message: '操作が成功しました'  # 任意：サンプルデータのメッセージ【string】
              # examples:  # 任意【Map[string, Example Object]】（割愛）
              # encoding: 任意【Map[string, Encoding Object]】（割愛）
        ### string(MapのKey) ###
        '400':  # 独自定義: ステータスコード（一つ以上必須）【string】
          ### 【Reference Object(MapのValue)】 ###
          $ref: '#/components/responses/badRequest'  # 必須: レスポンスの参照（参照記述）【Reference Object】
        ### string(MapのKey) ###
        default:  # 任意: デフォルトレスポンス【string】
          ### 【Response Object(MapのValue)】 ###
          description: エラーレスポンス  # 必須: レスポンスの説明【string】
          # headers: # 任意【Map[string, Header Object | Reference Object]】（割愛）
          content:  # 必須: レスポンスのコンテンツタイプとスキーマ【Map[string, Media Type Object]】
            ### string(MapのKey) ###
            application/json:  # 必須: コンテンツタイプ【string】
              ### 【Media Type Object(MapのValue)】 ###
              schema:  # 必須: スキーマの参照【Schema Object】
                ### 【Schema Object】 ###
                ### json-schema.orgを参照して記述する ###
                ## https://json-schema.org/draft/2020-12/vocab/core
                ## ⇒ JSON Schemaの基本的な構造やメタデータに関する定義が記載されている。
                ## https://json-schema.org/draft/2020-12/vocab/validation
                ## ⇒ JSON Schemaのバリデーションルールが定義されている。データ型（type）、制約（minimum, maximum, patternなど）、必須プロパティ（required）など、スキーマのバリデーションに関する詳細な情報も記載。
                type: object  # 必須: オブジェクト型のスキーマ【string】
                properties:  # 必須: オブジェクトのプロパティ【Map[string, Schema Object]】
                  error:  # 必須: プロパティの名前【string】
                    type: string  # 必須: プロパティのタイプ【string】
                    description: エラーメッセージ  # 任意: プロパティの説明【string】
                    example: 'ERRORが発生しました'  # 任意: プロパティの例【any】
              example: 'エラーが発生しました'  # 任意: プロパティの例【any】
              # examples:  # 任意【Map[string, Example Object]】（割愛）
              # encoding: 任意【Map[string, Encoding Object]】（割愛）
      # callbacks:  # 任意【Map[string, Callback Object | Reference Object]】（割愛）
      # deprecated:  # 任意【boolean】（割愛）
      security:  # 任意: エンドポイントのセキュリティ設定【[Security Requirement Object]】
        ### 【Security Requirement Object】 ###
        - bearerAuth: []  # 独自定義: セキュリティスキームの参照【string】
      # servers:  # 任意【[Server Object]】（割愛）
ルートレベルの例：components【Components Object】
components:  # 任意: 再利用可能なスキーマ、レスポンス、パラメータ、リクエストボディ、セキュリティスキームなどを定義【Components Object】
  schemas:  # 任意: 再利用可能なスキーマの定義【Map[string, Schema Object]】
    ### string(MapのKey) ###
    CustomerInfoRequestBody:  # 独自定義: 顧客情報リクエストのスキーマ【string】
      ### 【Schema Object(MapのValue)】 ###
      ### json-schema.orgを参照して記述する ###
      ## https://json-schema.org/draft/2020-12/vocab/core
      ## ⇒ JSON Schemaの基本的な構造やメタデータに関する定義が記載されている。
      ## https://json-schema.org/draft/2020-12/vocab/validation
      ## ⇒ JSON Schemaのバリデーションルールが定義されている。データ型（type）、制約（minimum, maximum, patternなど）、必須プロパティ（required）など、スキーマのバリデーションに関する詳細な情報も記載。
      type: object  # 必須: スキーマのタイプ【string】
      properties:  # 必須: スキーマのプロパティ【object】
        customerId:  # 独自定義: プロパティ【object】
          type: string  # 必須: プロパティのタイプ【string】
          description: 説明  # 任意: プロパティの説明【string】
          example: 'hogehoge'  # 任意: プロパティの例【any】
    ### string(MapのKey) ###
    TestAccountInfoResponse:  # 独自定義: 銀行口座情報レスポンスのスキーマ【string】
      ### 【Schema Object(MapのValue)】 ###
      ### json-schema.orgを参照して記述する ###
      ## https://json-schema.org/draft/2020-12/vocab/core
      ## ⇒ JSON Schemaの基本的な構造やメタデータに関する定義が記載されている。
      ## https://json-schema.org/draft/2020-12/vocab/validation
      ## ⇒ JSON Schemaのバリデーションルールが定義されている。データ型（type）、制約（minimum, maximum, patternなど）、必須プロパティ（required）など、スキーマのバリデーションに関する詳細な情報も記載。
      type: object  # 必須: スキーマのタイプ【string】
      properties:  # 必須: スキーマのプロパティ【object】
        testName:  # 独自定義: プロパティ【object】
          type: string  # 必須: プロパティのタイプ【string】
          description: 名前  # 任意: プロパティの説明【string】
        accountNumber:  # 独自定義: プロパティ【object】
          type: string  # 必須: プロパティのタイプ【string】
          description: 説明  # 任意: プロパティの説明【string】
  responses:  # 任意: 再利用可能なレスポンスの定義（components配下は予約語のresponsesの使用が推奨される）【Map[string, Response Object | Reference Object]】
    ### string(MapのKey) ###
    badRequest:  # 独自定義: 不正なリクエストのレスポンス【string】
      ### 【Response Object(MapのValue)】 ###
      description: 不正なリクエスト  # 必須: レスポンスの説明【string】
      # headers: # 任意【Map[string, Header Object | Reference Object]】（割愛）
      content:  # 必須: レスポンスのコンテンツタイプとスキーマ【object】
        ### string(MapのKey) ###
        application/json:  # 必須: コンテンツタイプ【object】
          ### 【Media Type Object(MapのValue)】 ###
          schema:  # 必須: スキーマの定義【object】
            ### 【Schema Object】 ###
            ### json-schema.orgを参照して記述する ###
            ## https://json-schema.org/draft/2020-12/vocab/core
            ## ⇒ JSON Schemaの基本的な構造やメタデータに関する定義が記載されている。
            ## https://json-schema.org/draft/2020-12/vocab/validation
            ## ⇒ JSON Schemaのバリデーションルールが定義されている。データ型（type）、制約（minimum, maximum, patternなど）、必須プロパティ（required）など、スキーマのバリデーションに関する詳細な情報も記載。
            type: object  # 必須: スキーマのタイプ【string】
            properties:  # 必須: スキーマのプロパティ【object】
              message:  # 任意: エラーメッセージのプロパティ【object】
                type: string  # 必須: プロパティのタイプ【string】
                description: エラーメッセージ  # 任意: プロパティの説明【string】
  parameters:  # 任意: 再利用可能なパラメータの定義（components配下は予約語のparametersの使用が推奨される）【Map[string, Parameter Object | Reference Object]】
    ### string(MapのKey) ###
    testId:  # 独自定義: 再利用可能なパラメータの名前【string】
      ### 【Parameter Object(MapのValue)】 ###
      name: testId  # 必須: パラメータの名前（直接記述）【string】
      in: query # 必須: パラメータの場所（例: query, header, path, cookie）【string】
      required: true  # 必須: パラメータが必須かどうか【boolean】
      ### deprecated: # 任意【boolean】（割愛）
      ### allowEmptyValue: # 任意【boolean】（割愛）
      style: form  # 任意: パラメータのスタイル（matrix, label, form, simple, spaceDelimited, pipeDelimited, deepObject）【string（default値はinの値に応じて変わる）】
      # explode: # 任意【boolean（default値はinの値に応じて変わる）】（割愛）
      # allowReserved: # 任意【boolean（default値はfalse扱い）】（割愛）
      schema:  # 必須: パラメータのスキーマ【Schema Object】
        ### 【Schema Object】 ###
        ### json-schema.orgを参照して記述する ###
        ## https://json-schema.org/draft/2020-12/vocab/core
        ## ⇒ JSON Schemaの基本的な構造やメタデータに関する定義が記載されている。
        ## https://json-schema.org/draft/2020-12/vocab/validation
        ## ⇒ JSON Schemaのバリデーションルールが定義されている。データ型（type）、制約（minimum, maximum, patternなど）、必須プロパティ（required）など、スキーマのバリデーションに関する詳細な情報も記載。
        type: string  # 必須: パラメータのタイプ【string】
      description: パラメータの説明  # 任意: パラメータの説明【string】
  # examples:  # 任意【Map[string, Example Object]】（割愛）
  # requestBodies:  # 任意【Map[string, Request Body Object | Reference Object]】（割愛）
  # headers:  # 任意【Map[string, Header Object | Reference Object]】（割愛）
  # securitySchemes:  # 任意【Map[string, Security Scheme Object | Reference Object]】（割愛）
  # links:  # 任意【Map[string, Link Object | Reference Object]】（割愛）
  # callbacks:  # 任意【Map[string, Callback Object | Reference Object]】（割愛）
  # pathItems:  # 任意【Map[string, Path Item Object | Reference Object]】（割愛）
ルートレベルの例：割愛
# security:  # 任意【Map[string, Security Requirement Object]】（割愛）
# tags:  # 任意【[Tag Object]】（割愛）
# externalDocs:  # 任意【External Documentation Object】（割愛）

記載内容の補足

「-」

リストを表現

servers:
  - url: /api/v1
    description: バージョン1のAPI
  - url: /api/v2
    description: バージョン2のAPI

「リクエストボディの定義方法」

HTTPメソッド parameters requestBody responses
GET 任意 指定不可 必須
PUT 任意 任意 必須
POST 任意 任意 必須
DELETE 任意 指定不可 必須
OPTIONS 任意 指定不可 必須
HEAD 任意 指定不可 必須
PATCH 任意 任意 必須
TRACE 任意 指定不可 必須

「in」

parameters:
  - name: param1
    in: query
    required: true
    schema:
      type: string
    description: クエリパラメータの説明
  • header
    HTTP ヘッダーに含まれるパラメータ。リクエストやレスポンスのメタデータとして使用される。
    使用例: Authorization: Bearer 
parameters:
  - name: X-Custom-Header
    in: header
    required: false
    schema:
      type: string
    description: ヘッダーパラメータの説明

parameters:
  - name: id
    in: path
    required: true
    schema:
      type: string
    description: パスパラメータの説明
  • cookie
    HTTP クッキーに含まれるパラメータ。クライアントとサーバー間で状態を維持するために使用される。
    使用例: Cookie: sessionId=abc123
parameters:
  - name: sessionId
    in: cookie
    required: true
    schema:
      type: string
    description: クッキーパラメータの説明
inの設定値 用途 使用例
query リクエストの動作変更に使用 検索クエリ、ソート順、ページ番号など
header リクエストのメタデータ提供に使用 認証トークン、カスタムヘッダー
path リソースを一意に識別するのに使用 リソース ID、ユーザー名など
cookie クライアントとサーバー間の状態維持に使用 セッション ID、トラッキング情報など
inの設定値 required style(デフォルト値) allowReserved
query 任意 form false
header 任意 simple -(使用不可)
path 必須 simple -(使用不可)
cookie 任意 form -(使用不可)
inの設定値 styleの設定値 explodeのデフォルト値
query form true
spaceDelimited false
pipeDelimited false
deepObject true
header simple false
path simple false
matrix false
label false
cookie form true
0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?