はじめに

業務でOpenAPIを用いたAPI設計を行っているため、備忘録も兼ねてまとめる。
入門用なので、基本的な部分のみ解説。

概要

OpenAPI

What Is OpenAPI?
OpenAPIとは、RESTful APIを記述するためのフォーマットのこと。
Swagger 2.0を拡張して実装されている。

Swagger

Swaggerとは、OpenAPIを用いてREST APIを設計する際に使用するツールセットのこと。

メジャーなものとしては以下。

ツール名	概要
Swagger Editor	ブラウザベースでOpenAPIを記述できるエディター。Dockerイメージも配布されており、ローカルでの実行も可能。
Swagger UI	OpenAPIの記述を、動的にAPIドキュメントとしてレンダリングするツール。上記のSwagger Editorの右半分に出ているのはコレ。
Swagger Codegen	OpenAPIの記述から、サーバー/クライアントのコードを生成するツール。多くの言語に対応。

記述形式

OpenAPIの記述は以下の2種類から選択可能。
どちらの形式で記述しても、アウトプットは同じ。
またYAML→JSON、JSON→YAMLの相互変換が可能。(Swagger Editorの機能)

YAML形式
JSON形式

基本構造

本記事では、YAML形式で記述していく。

sample.yaml

openapi: 3.0.0
info:
  ...
servers:
  ...
paths:
  ...
components:
  ...
security:
  ...
tags:
  ...
externalDocs:
  ...

フィールド名	必須	概要
openapi	YES	セマンティックなバージョニングを記述する。今回は`3.0.0`を用いる。詳しくはドキュメントを参照。
info	YES	APIのメタデータを記述する。
servers		APIを提供するサーバーを記述する。配列で複数記述可能(STG, PROD等)。
paths	YES	APIで利用可能なエンドポイントやメソッドを記述する。
components	YES	APIで使用するオブジェクトスキーマを記述する。
security		API全体を通して使用可能なセキュリティ仕様を記述する。(OAuth等)
tags		APIで使用されるタグのリスト。各種ツールによってパースされる際は、記述された順序で出力される。タグ名はユニークで無ければならない。
externalDocs		外部ドキュメントを記述する(API仕様書等)。

各フィールドの詳細

`info`

ドキュメント: Info Object

example.yaml

info:
  title: Sample API
  description: A short description of API.
  termsOfService: http://example.com/terms/
  contact:
    name: API support
    url: http://www.example.com/support
    email: support@example.com
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.0

フィールド名	必須	概要
title	YES	APIの名称。
description		APIの簡潔な説明。CommonMarkシンタックスが使える。
termsOfService		APIの利用規約。URL形式でなければならない。
contact		コンタクト情報。(サポートページのURLやメールアドレス等)
license		ライセンス情報。ライセンスページのURLも記述可能。
version	YES	APIドキュメントのバージョン。

Swagger UIでの表示

`servers`

ドキュメント: Server Object

example.yaml

servers:
  - url: https://dev.sample-server.com/v1
    description: Development server
  - url: https://stg.sample-server.com/v1
    description: Staging server
  - url: https://api.sample-server.com/v1
    description: Production server

フィールド名	必須	概要
url	YES	APIサーバーのURL。
description		APIサーバーの説明。

Swagger UIでの表示
複数の場合、ドロップダウンで表示される。

`paths`

ドキュメント: Paths Object

example.yaml

paths:
  # paths オブジェクト
  /users:
    # path item オブジェクト
    get: # GET
      # Operationオブジェクト
      tags:
        - users
      summary: Get all users.
      description: Returns an array of User model
      parameters: []
      responses: # レスポンス定義
        '200': # HTTP status
          description: A JSON array of User model
          content:
            application/json: # レスポンスの形式指定
              schema: 
                type: array
                items:
                  $ref: '#/components/schemas/User' # 参照するモデル
                example: # サンプルデータ
                  - id: 1
                    name: John Doe
                  - id: 2
                    name: Jane Doe
    post: # POST
      tags: 
        - users
      summary: Create a new User
      description: Create a new User
      parameters: []
      requestBody: # リクエストボディ
        description: user to create
        content:
          application/json:
            schema: # POSTするオブジェクト
              $ref: '#/components/schemas/User'
            example:
              id: 3
              name: Richard Roe
      responses:
        '201':
          description: CREATED
  /users/{userId}:
    get:
      tags:
        - users
      summary: Get user by ID.
      description: Returns a single User model
      parameters: # リクエストパラメータ
        - name: userId
          in: path # パラメータをパス内に含める
          description: user id
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: A single User model
          content:
            application/json:
              schema: 
                type: object
                items:
                  $ref: '#/components/schemas/User'
                example:
                  id: 1
                  name: John Doe

`paths`オブジェクト

|フィールド名|概要|
|:--|:--|:--|
|/{path}|各エンドポイントのパスを記述する。serversで定義したURLにこのパスを結合したものが最終的なエンドポイントとなる。|

`path item`オブジェクト

Swagger UIでの表示

`components`

ドキュメント: Components Object

schemas: UserやProduct等のモデル
requestBodies: リクエストボディ
responses: APIレスポンス
headers: リクエストヘッダ
parameters: リクエストパラメータ

等、API定義で再利用可能なオブジェクトを定義できる。

componentsフィールドに定義したモデルは、pathsで記述したように

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

のように参照する。

example.yaml

components:
  schemas: # スキーマオブジェクトの定義
    User: # モデル名
      type: object # 型
      required: # 必須フィールド
        - id
      properties:
        id: # プロパティ名
          type: integer # 型 
          format: int64 # フォーマット(int32, int64等)
        name:
          type: string
    Product:
      type: object
      required:
        - id
        - price
      properties:
        id:
          type: integer
          format: int64
          example: 1
        name:
          type: string
          example: Laptop
        price:
          type: integer
          example: 1200

Swagger UIでの表示
Modelエリアに表示され、構造やサンプル値が参照できる。

`security`

ドキュメント: Security Requirement Object

example.yaml

security: 
  # Non-OAuth setting
  - api_key: []
  # OAuth setting
  - users_auth:
    - write:users
    - read:users

Swagger UIでの表示
メソッド定義部分に鍵マークが表示される。

`tags`

ドキュメント: Tag Object

example.yaml

tags:
  - name: users
    description: Access to Users
  - name: products
    description: Access to Products

フィールド名	必須	概要
name	YES	タグ名称。
description		タグの説明。
externalDocs		外部ドキュメント

Swagger UIでの表示
各エンドポイントでtagsに指定することで、定義をタグで分類できる。

`externalDocs`

ドキュメント: External Documentation Object

example.yaml

description: Find more info here
url: https://example.com

フィールド名	必須	概要
description		外部ドキュメントの説明。
url	YES	外部ドキュメントのURL。

Swagger UIでの表示
ドキュメント上部にリンクが表示される。

まとめ

以上、OpenAPIの基本的な部分を紹介した。
OpenAPIはSwagger 2.0をベースにしているが、記法が異なる部分が多いため、公式ドキュメントをしっかり読み込んで行く必要がある。
手軽にRESTful APIの定義ができるうえ、Amazon API Gatewayと連携し定義のインポート/エクスポートが出来たりと非常に便利なため、ぜひ使ってみてほしい。

Swagger 定義をインポートしてエッジ最適化 API をセットアップする
 API Gateway から API をエクスポートする

今回作成したサンプル

参考

Swagger Documentation
OpenAPI Specification

はじめに

概要

OpenAPI

Swagger

記述形式

基本構造

各フィールドの詳細

info

servers

paths

pathsオブジェクト

path itemオブジェクト

components

security

tags

externalDocs

まとめ

今回作成したサンプル

参考

`info`

`servers`

`paths`

`paths`オブジェクト

`path item`オブジェクト

`components`

`security`

`tags`

`externalDocs`