最もシンプルなOpenAPI(YAMLで記述するAPI定義書)

以下の３つは絶対必要
openapi(バージョン)
info(ヘッダ的フィールド)
paths(APIのアクセスポイント)

openapi: 3.0.0 # openapiのバージョン

info: # ヘッダ的フィールド
  title: Test API # このドキュメントのタイトル
  version: 0.0.1 # このドキュメントのバージョン

paths: # APIのアクセスポイント  
  /hello: # パス名(api/helloみたいな感じでアクセスする)
    get: # メソッド名(get/post/put/delete)
      responses: # アクセスしたら、どんなレスポンスを返すか？
        '200': # HTTPレスポンス番号
          description: helloという文字列を返す # 説明は必須(summaryは必須じゃない)
          content: # レスポンスの内容
            application/json: # レスポンスの形式指定(MIMEタイプ)
              schema: # データ構造(schema = 構造)
                type: object # integer,stringなどの型。objectは複数データをもつ型
                properties: # objectの中身を羅列する
                  answer: # プロパティ名
                    type: string # プロパティの型
                    example: "world!!" # どんな文字列か？

openapi: 3.0.0 # openapiのバージョン

info: # ヘッダ的フィールド

title: Test API # このドキュメントのタイトル

version: 0.0.1 # このドキュメントのバージョン

paths: # APIのアクセスポイント

/hello: # パス名(api/helloみたいな感じでアクセスする)

get: # メソッド名(get/post/put/delete)

responses: # アクセスしたら、どんなレスポンスを返すか？

'200': # HTTPレスポンス番号

description: helloという文字列を返す # 説明は必須(summaryは必須じゃない)

content: # レスポンスの内容

application/json: # レスポンスの形式指定(MIMEタイプ)

schema: # データ構造(schema = 構造)

type: object # integer,stringなどの型。objectは複数データをもつ型

properties: # objectの中身を羅列する

answer: # プロパティ名

type: string # プロパティの型

example: "world!!" # どんな文字列か？

preview swaggerでyamlを表示する(OpenAPI3.0 = swagger3.0)

1, tagsフィールド(APIをまとめるためのタグ)
2, componentsフィールド(構造を書く場所)
を追加

openapi: 3.0.0 # openapiのバージョン

info: # ヘッダ的フィールド
  title: Test API # このドキュメントのタイトル
  version: 0.0.1 # このドキュメントのバージョン

tags: # 各APIをグループ化してまとめるためのタグ
  - name: first_api # タグ名
    description: APIその１ # タグの説明

paths: # APIのアクセスポイント  
  /hello: # パス名(api/helloみたいな感じでアクセスする)
    get: # メソッド名(get/post/put/delete)
      tags:
        - first_api    
      responses: # アクセスしたら、どんなレスポンスを返すか？
        '200': # HTTPレスポンス番号
          description: helloという文字列を返す # 説明は必須(summaryは必須じゃない)
          content: # レスポンスの内容
            application/json: # レスポンスの形式指定(MIMEタイプ)
              schema: # データ構造(schema = 構造)
                # シャープは同じファイルを意味する(リンク先を記述)
                $ref: '#/components/schemas/get_hello_response' 

# ここに個別のスキーマ(構造)情報を書く                  
components:
  schemas: # スキーマは、戻り値のデータ？
    get_hello_response: # スキーマ名
      type: object # integer,stringなどの型。objectは複数データをもつ型
      properties: # objectの中身を羅列する
        answer: # プロパティ名
          type: string # プロパティの型
          example: "world!!" # どんな文字列か？

openapi: 3.0.0 # openapiのバージョン

info: # ヘッダ的フィールド

title: Test API # このドキュメントのタイトル

version: 0.0.1 # このドキュメントのバージョン

tags: # 各APIをグループ化してまとめるためのタグ

- name: first_api # タグ名

description: APIその１ # タグの説明

paths: # APIのアクセスポイント

/hello: # パス名(api/helloみたいな感じでアクセスする)

get: # メソッド名(get/post/put/delete)

tags:

- first_api

responses: # アクセスしたら、どんなレスポンスを返すか？

'200': # HTTPレスポンス番号

description: helloという文字列を返す # 説明は必須(summaryは必須じゃない)

content: # レスポンスの内容

application/json: # レスポンスの形式指定(MIMEタイプ)

schema: # データ構造(schema = 構造)

# シャープは同じファイルを意味する(リンク先を記述)

$ref: '#/components/schemas/get_hello_response'

# ここに個別のスキーマ(構造)情報を書く

components:

schemas: # スキーマは、戻り値のデータ？

get_hello_response: # スキーマ名

type: object # integer,stringなどの型。objectは複数データをもつ型

properties: # objectの中身を羅列する

answer: # プロパティ名

type: string # プロパティの型

example: "world!!" # どんな文字列か？

関連記事