解説：Swagger（OpenAPI）の 仕様書の書き方

SwaggerやOpenAPIは、API業界標準の仕様になります。API設計を標準化にしたりする必要がある場合、SwaggerやOpenAPI仕様書の書き方をマスタする必要があるのでしょう。本文では、SwaggerとOpenAPIの仕様書の書き方を皆さんに詳しく解説するので、必要な方は本文の内容を参照してください。

また、SwaggerやOpenAPIの仕様にも完璧に互換なApidogを使って、非常に綺麗なAPI仕様書を自動生成する方法を皆さんに紹介します。

SwaggerとOpenAPIとは

SwaggerとOpenAPIはAPIの定義とドキュメント化のためのフレームワークです。

Swaggerは最初にSmartBear Softwareによって作成されたOSSのフレームワークで、APIの定義やインタラクティブなドキュメントを自動生成できます。OpenAPIはSwagger 2.0仕様をベースにした業界標準の仕様です。

最近のバージョンとしてはOpenAPI 3.0があり、JSON/YAMLファイルでAPIを定義できるほか、豊富な機能が追加されています。多くの場合このOpenAPI 3.0仕様に準拠したSwaggerツールを利用するのが一般的です。

Swagger（OpenAPI）の 仕様書の書き方

Swagger（OpenAPI）の 仕様書の書き方といえば、YAMLとJSONといった形式を避けることができないのでしょう。OpenAPIの仕様書は主にYAMLやJSON形式で記述します。

YAML形式

• YAMLはインデントによる階層構造を表現できる形式
• 視認性が高く、構造的に記述しやすい
• インデント、スペース、大文字小文字に注意
• OpenAPIのRoot要素から順に、情報、サーバー、パス、コンポーネントを記述

JSON形式

• JSONは{}や[]による階層構造
• YAMLよりも若干冗長だが、プログラミング言語との親和性が高い
• 構造的にはYAMLと同じ順序で記述
• オブジェクトは{}、配列は[]で表現
• キーとバリューのペアで要素を定義

このように、YAMLとJSONそれぞれに特徴があります。

YAMLの方が直感的で視認性が高い反面、JSONはプログラマにとってなじみやすい構造です。目的と開発スタイルに合わせて、適切な形式を選択していくことが重要です。どちらもOpenAPIの標準仕様に従えばAPI定義が可能です。次は、この2つの形式を利用して、OpenAPIの仕様書を書く方法を別々に紹介していきたいと思います。

YAMLでOpenAPI仕様書を書く

YAMLとは、YAML Ain't Markup Languagの略語として再帰的頭字語を意味して、データをシリアライズするためのテキストベースのマークアップ言語です。OpenAPI仕様の標準形式の1つとして、APIを記述してAPI仕様書・設計書を作成する際、yaml形式が非常に汎用されています。

yamlでAPI仕様書・設計書を記述する際、OpenAPI（Swagger）仕様に準拠する必要があります。そして、エンドポイント、パラメータ、リクエストボディやレスポンスなどの情報を記述する必要があります。

例えば、ユーザー情報を取得するシンプルなAPIの仕様書は以下のようにYAMLで記述できます。

openapi: 3.0.0
info:
  title: User API
  version: 1.0.0
servers:
  - url: https://example.com/api/v1

paths:
  /users/{userId}:
    get:
      summary: Get a user
      parameters:
        - in: path
          name: userId
          required: true
          description: User identifier
          schema:
            type: integer
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
              
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string

• 最上位にopenapiバージョン、APIのタイトル、バージョン等の基本情報を定義
• serversでエンドポイントのURLを指定
• pathsでエンドポイントごとのパスとメソッドを定義
• parametersにパスパラメーター、responsesにレスポンスを記述
• componentsでデータ構造を参照

このように、YAMLの特徴を活かしたインデント構造と、OpenAPI標準の仕様でAPI定義を作成することができます。ただし、yaml形式の仕様書は、上記のコードのままになりますが、この仕様書をより直感的に表示させるには、yamlファイルをApidogにインポートして、yamlのAPI仕様書を可視化にすることができます。

JSONでOpenAPI仕様書を書く

JSONはJavaScript Object Notationの略で、データを記述するための軽量なデータ交換フォーマットです。OpenAPIではYAMLと並ぶ主要な定義ファイルのフォーマットとしてJSONがサポートされています。

JSONで記述した場合は、基本的な構造はYAMLと同じですが、表記法が異なります。

例えば、上記のユーザー情報取得APIは、JSONで以下のように記述できます。

{
  "openapi": "3.0.0",
  "info": {
    "title": "User API",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://example.com/api/v1"
    }
  ],

  "paths": {
    "/users/{userId}": {
      "get": {
        "summary": "Get a user",
        "parameters": [
          {
            "in": "path",
            "name": "userId",
            "required": true,
            "description": "User identifier",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/User"
                }
              }
            }
          }
        }
      }
    }
  },

  "components": {
    "schemas": {
      "User": {
        "type": "object", 
        "properties": {
          "id": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "email": {
            "type": "string"
          }
        }
      }
    }
  }
}

• 最上位のopenapiキーではバージョンが3.0.0と定義されています。
• infoオブジェクトでは、APIのタイトルとバージョンが記述されています。
• servers配列では、APIのエンドポイントURLが定義されています。
• pathsオブジェクト内で、/users/{userId}のパスに対してget操作が定義されています。
• getオブジェクト内では、summary、parameters、responsesが定義されています。
• parameters配列では、パスパラメータuserIdが定義されています。
• responsesオブジェクトでは、200レスポンスが定義され、Userスキーマが参照されています。
• componentsオブジェクト内で、Userスキーマが定義されており、id、name、emailのプロパティがあるobjectとなっています。

このように、OpenAPIの仕様構造に沿ってAPIのエンドポイント、操作、パラメータ、レスポンス、データ構造がJSON形式で定義されています。

JSONやYAMLにも対応：Apidogは綺麗な仕様書を生成

API管理が必要となる場合は、一番使いやすいAPI管理ツールのApidogを使用すると、JSONやyaml形式のAPIを簡単にインポートして、直感的な仕様書を生成したり、APIをテストしたりすることができます。

JSONやYAMLを簡単にインポート

ApidogはJSONやYAMLフォーマットのOpenAPI 3、Swagger 1、2、3のAPIをインポートすることをサポートしているので、YAMLやJSONフォーマットのAPIを完全に解析して、APIのデータを完全にApidogにインポートしてテストできます。

ステップ⒈プロジェクトの設定を開き、「データをインポート」をクリックすると、「OpenAPI/Swagger」を選択して、YAMLファイルをApidogにドラッグします。

ステップ⒉ここでYAMLファイルが解析され、データの保存先を選択すると、「確認」ボタンをクリックするだけで、それを簡単にApidogにインポートできます。

そして、ApidogというAPI管理ツールを使って、当該APIをテストしたりすることができるようになりますし、APIリクエストを送信して直ちに内蔵のモックサーバーを使って仮のレスポンスデータを取得することもできます。

yamlやJSONで綺麗なAPI仕様書を自動生成

また、yamlかJSONファイルをApidogにインポートすると、Apidogは、yaml・JSONファイルで記述されている情報に基づいて、非常に魅力的なAPI仕様書を自動的に生成してくれますし、この仕様書を簡単に他の人に共有することもできるので、非常に便利です。