📑

Swagger(OpenAPI3.0)に入門する(基本構成編)

2022/08/19に公開約6,400字

この記事は,下記のサイトを参考にしています。

https://swagger.io/docs/specification/basic-structure/

基本構成

OpenAPI の定義は、YAML あるいは JSON で記述することができます。
YAML で書かれた OpenAPI 3.0 の定義のサンプルは、次のようになります。

openapi: 3.0.0
info:
  title: Sample API
  description: Optional multiline or single-line description in [CommonMark](http://commonmark.org/help/) or HTML.
  version: 0.1.9
servers:
  - url: http://api.example.com/v1
    description: Optional server description, e.g. Main (production) server
  - url: http://staging-api.example.com
    description: Optional server description, e.g. Internal staging server for testing
paths:
  /users:
    get:
      summary: Returns a list of users.
      description: Optional extended description in CommonMark or HTML.
      responses:
        '200':    # status code
          description: A JSON array of user names
          content:
            application/json:
              schema: 
                type: array
                items: 
                  type: string

大文字と小文字は区別されます。

Metadata

すべてのAPI定義には、OpenAPI仕様のバージョンを含める必要があります。

openapi: 3.0.0

OpenAPIのバージョンは、API定義の全体的な構造、つまり、何をどのように文書化するかを定義します。

infoセクションには、title、description(任意項目)、versionなどの項目を含めます。

info:
  title: Sample API
  description: Optional multiline or single-line description in [CommonMark]
  version: 0.1.9
  • title : APIの名称
  • description : APIに関する拡張情報。説明文は複数行にすることもできる。CommonMarkもサポートされている。
  • version : APIのバージョンを指定する任意の文字列。(openapiバージョンと混同しないこと)major.minor.patchのようなセマンティックバージョニングでも、1.0-betaや2017-07-25のような任意の文字列も記載できる。

このほかに、termsOfService、contact、licenseなどの情報を記載できます。

Servers

serversセクションには、APIサーバとベースURLを指定できます。本番用やサンドボックス用など、1つまたは複数のサーバを定義することができます。

servers:
  - url: http://api.example.com/v1
    description: Optional server description, e.g. Main (production) server
  - url: http://staging-api.example.com
    description: Optional server description, e.g. Internal staging server for testing

すべてのAPIパスは、相対パスです。
上記の例では、/usersは、使用するサーバーに応じて、http://api.example.com/v1/users または http://staging-api.example.com/users となります。

Paths

pathsセクションは、APIにおける個々のエンドポイントと、サポートするHTTPメソッドを定義します。例えば、GET /usersは、以下のように記述することができます。

paths:
  /users:
    get:
      summary: Returns a list of users.
      description: Optional extended description in CommonMark or HTML.
      responses:
        "200": # status code
          description: A JSON array of user names
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string

Parameters

操作には、URL path(/users/{userId})、query string(/users?role=admin)、headers (X-CustomHeader: Value)、cookies(Cookie: debug=0)経由でパラメータを渡すことが可能です。パラメータのデータ型、フォーマット、必須か任意か、その他の詳細を定義することができます。

paths:
  /users/{userId}:
    get:
      summary: Returns a user by ID.
      parameters:
        - name: userId
          in: path
          required: true
          description: Parameter description in CommonMark or HTML.
          schema:
            type : integer
            format: int64
            minimum: 1
      responses: 
        '200':
          description: OK

Request Body

操作でrequest bodyを送信する場合は、requestBody キーワードを使用してcontent およびmedia typeを記述します。

paths:
  /users:
    post:
      summary: Creates a user.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                username:
                  type: string
      responses: 
        '201':
          description: Created

Responses

各操作に対して、200 OK や 404 Not Found などのステータスコードと、 レスポンスボディのスキーマを定義することができます。スキーマはインラインで定義することも、$ref で参照することもできます。また、さまざまなコンテンツタイプに対するレスポンスの例を提供することもできます。

paths:
  /users/{userId}:
    get:
      summary: Returns a user by ID.
      parameters:
        - name: userId
          in: path
          required: true
          description: The ID of the user to return.
          schema:
            type: integer
            format: int64
            minimum: 1
      responses:
        '200':
          description: A user object.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    format: int64
                    example: 4
                  name:
                    type: string
                    example: Jessica Smith
        '400':
          description: The specified user ID is invalid (not a number).
        '404':
          description: A user with the specified ID was not found.
        default:
          description: Unexpected error

レスポンスの HTTP ステータスコードは、引用符で囲む必要があることに注意してください。
"200" (OpenAPI 2.0 では不要でした)

Input and Output Models

グローバルコンポーネント/スキーマセクションでは、APIで使用する共通のデータ構造を定義することができます。これらは、パラメータやリクエストボディ、レスポンスボディなど、 スキーマが必要なときにいつでも $ref を使って参照することができます。たとえば、この JSON のようなものです。

{
  "id": 4,
  "name": "Arthur Dent"
}

上記を下記のように表現することができます。

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          example: 4
        name:
          type: string
          example: Arthur Dent
      # Both properties are required
      required:  
        - id
        - name

そうすると、以下のようにリクエストボディスキーマとレスポンスボディスキーマで参照できるようになります。

paths:
  /users/{userId}:
    get:
      summary: Returns a user by ID.
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: integer
            format: int64
            minimum: 1
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'    # <-------ここ
  /users:
    post:
      summary: Creates a new user.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'      # <-------ここ
      responses:
        '201':
          description: Created

Authentication

securitySchemesおよびsecurityキーワードは、APIで使用する認証方法を記述するために使用されます。

components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
security:
  - BasicAuth: []

Full Specification

OpenAPI 3.0仕様の全文は、GitHubで公開されています。

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md

Discussion

ログインするとコメントできます