最もシンプルなOpenAPI(YAMLで記述するAPI定義書)
以下の３つは絶対必要
openapi(バージョン)
info(ヘッダ的フィールド)
paths(APIのアクセスポイント)
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
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フィールド(構造を書く場所)
を追加
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 |
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!!" # どんな文字列か？ |
