OpenAPI仕様とは、使いやすい記述ツールをご紹介！

現在アプリケーションの開発中に、APIを導入して機能を拡張したりすることが非常に普通なことになっています。そんな中、OpenAPIはAPI仕様のフォーマットとして開発者によく知られています。本文では、OpenAPIについて詳しく紹介する上、OpenAPI仕様を記述するツールを皆さんに紹介します。

OpenAPI仕様とは

OpenAPI仕様とは、APIの仕様を記述するための標準規格です。最近では多くのWeb APIがOPENAPI形式で公開されており、REST APIの仕様記述と公開の標準フォーマットとして広く利用されています。

OpenAPI仕様といえば、主な特徴は以下の通りです。

• APIの仕様をJSONやYAMLファイルで記述できる
• APIのエンドポイント、パラメータ、レスポンスなどの定義ができる
• インタラクティブなドキュメントを生成できる
• さまざまなプログラミング言語でAPIクライアントのコードを自動生成できる

OPENAPIの仕様ファイルを公開することで、開発者は簡単にAPIの利用方法を理解でき、クライアントコードの開発がしやすくなります。また、OPENAPIに準拠したAPIはツールとの互換性が高く、APIモックの作成、テストの自動化、モニタリングなどが行いやすくなります。

OpenAPI仕様のサンプル

それでは、OpenAPI仕様はどのようなものですか？OpenAPIではYAMLやJSON形式でAPIのエンドポイント、メソッド、パラメータ、スキーマなどを定義します。次は、OpenAPIの仕様ファイルのサンプルを示します。

openapi: 3.0.0
info:
  title: APIサンプル
  description: APIサンプル
  version: 1.0.0

servers:
  - url: http://api.example.com

paths:
  /users:
    get:
      summary: ユーザーリストを返す。
      responses:
        200:
          description: ユーザー名を含むJSON配列を記述
          content:
            application/json:
              schema: 
                type: array
                items:
                  type: string          

以上のサンプルでは、/usersエンドポイントに対するGETメソッドを定義しています。

• /usersにGETリクエストをすると、ユーザ名のリストをJSON配列で返す
• レスポンスのスキーマは文字列の配列

といったAPIの仕様がコードとして記述されています。

また、当該APIのレスポンスを詳しく定義する場合は、最後にあるResponsesの「Content」の下に、JSONデータを詳しくする必要もあります。そうすると、content部分の内容は次のようになります。

　　　　　　 content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                      description: ユーザーID
                    name:
                      type: string
                      description: ユーザー名
                example:
                  - id: 1
                    name: 田中
                  - id: 2 
                    name: 清水

このようにして、このAPIにリクエストを送信すると、レスポンスの内容は、ユーザーIDとユーザー名といった情報を返すようになります。

上記のように、OpenAPI仕様は、構造化されたデータによって、APIの構造をはっきりとしていて、非常にわかりやすいのです。強いて欠点を言うなら、YAMLかJSONデータを手動で記述するのはちょっと面倒くさくなります。それでは、もし手動でYAMLやJSONを入力したくない場合は、OpenAPI仕様ファイルを生成する方法がありますか？次は、OpenAPI互換の記述ツールを皆さんに紹介します。

直感なUIでOpenAPI仕様を生成するApidog

Apidogは、非常に綺麗なAPI仕様書を作成したり、自動生成したりできるAPI管理ツールです。Apidogの直感的なUIで、コードなしでも、APIの仕様を設定することができるので、非常に便利です。また、APIのレスポンスを定義するにも、JSONデータを手動で書く必要がなく、データ項目を追加して、データ値のタイプを選択するだけでやり遂げられます。Apidogを使用すると、YAMLかJSONを手動で入力する必要が全然なくなります。

ステップ⒈Apidogで既存のAPIを開くか、新しいAPIを新規に作成します。まずはAPIのHTTPメソッド、エンドポイント、名前、説明などの基本の情報を設定します。必要に応じてリクエストに必要なパラメータを設定したりすることもできます。

ステップ⒉そして、「Response」の部分に移動して、レスポンスのデータ構造を設定できます。異なるシナリオ別で複数のレスポンスを追加することも可能です。

ご案内：レスポンスのデータ構造を設定するときに、手動でJSONデータを書く必要がありません。ここで直感的なUIでデータ項目を追加して、その値のタイプ（StringやIntegerなど）を定義すればOKです。

ステップ⒊データ項目を設定したら、もう少し下にスクロールして、Responseの例の部分に移動して、 例を追加をクリックします。

ステップ⒋例の名称を「成功例」に設定します。ここで 自動生成をクリックして、先に設定したデータ構造に基づいてモックサーバーを利用して、Responseの例であるJSONデータが生成されます。そして、 OK をクリックしてこのResponseの例をAPIの仕様書に追加することもできます。