解説：yamlでAPI仕様書・設計書の作り方

APIの使い方や動作条件などの情報を正確に伝えるために、API仕様書を作成する必要があります。yamlはOpenAPIとSwaggerのデフォルト記述形式として、API設計書・仕様書を作成する時によく利用されています。本文では、yaml形式でAPI仕様書・設計書を作る方法を詳しく解説します。

API仕様書の作成にyamlが多い

YAMLとは、YAML Ain't Markup Languagの略語として再帰的頭字語を意味して、データをシリアライズするためのテキストベースのマークアップ言語です。

APIを記述してAPI仕様書・設計書を作成する際、yaml形式が汎用されている理由は次のようになります：

yamlはシンプルで読み書きが容易なデータ形式であるため。json等に比べると記述しやすい。
構造が視覚的にわかりやすいため。インデントによる階層構造が表現できる。
コメントアウトができるため。APIの解説などを書き加えられる。
言語・プラットフォームに依存しないデータ形式であるため。様々な言語で解析・利用できる。
OpenAPIやSwaggerなど、API定義でよく使われる標準仕様がYAMLに対応しているため。
容量が小さくて済むので、APIドキュメントとしてYAMLファイルを配布しやすいため。

このように、記述・読解のしやすさと汎用性から、YAMLはAPIの定義やドキュメント記述の定番の形式になると言っても過言ではありません。

yamlでAPI仕様書を作成する方法

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仕様書を可視化にすることができます。

YAMLの可視化ツール：Apdiog

Webアプリ開発中に、APIの仕様記述、ドキュメント、構成定義など、APIとの関連でYAMLは欠かせない存在ともなっています。OpenAPI・Swaggerデフォルトの仕様フォーマットはYAMLになるので、API領域ではYAMLは非常に汎用されているフォーマットになります。Yamlで記述しているAPIなら、Apidogはそれに完璧に対応できます。

button

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

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

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

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

button

yamlを綺麗なAPI仕様書に生成

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