Swaggerとは？

SwaggerとはAPIのドキュメントを作成するためのツールです。

公式説明によると「OpenAPI仕様に基づいて構築されたオープンソースツールセットでありREST APIの設計、作成、文書化に役立つツールです。」とのこと。

SwaggerにはSwagger Editer、Sawgger UI、Swagger Codegenなど色々なツールがあります。

今回はSwagger Editerというツールを使ってAPIのドキュメントを作成していきます。

Swagger Editer

Swagger Editerはブラウザでも使用できるSwaggerのファイル作成、編集ができるツールです。

画面の左側にコード、右側にドキュメントの完成時ビューが表示されています。

完成形を見ながらコードが書けるので非常に楽です。

またブラウザで動かせるので使うための手間がかからないのも利点です。

Swagger Editer の実際の画面

Swagger Editer で仕様書を作成してみる

それでは実際にSwagger Editer で仕様書を作っていきたいと思います。作っていくといってもSwagger Editer を開くとサンプルのコードが既に書かれているのでそれを自分が作成するAPIに合わせて編集していく形になります。

Swagger Editer では YAML または JSON 形式で書いていくことになりますが、標準ではYAMLで書いてあるので今回もYAMLで書いていきます。まずは基本的な形から見ていきましょう。

サンプルのコードでは以下の10個のオブジェクトで構成されています。

swagger

必須項目となっているswagger。ここには使用するswaggerのバージョンを記述します。

特に理由がなければ標準の2.0のままでOKです。

info

infoも必須項目です。APIの概要を説明するためのものです。内容は下記の表参照。

host

APIのホスト名を記入するところです。

basePath

hostに記入した部分以降のパスを記入します。

Swagger Editer のサンプルコードでは host が petstore.swagger.io で basePath が /v2 となっているので

APIのパスは http://petstore.swagger.io/v2/~のようになります。

tags

タグを定義するところです。

ここで定義したtags と後述する paths を紐付けてタグ毎に各パスを表示してくれるようになっています。

サンプルコードでは pet, store, user がtagsに該当し、それぞれの直下に書いてある部分がパスに該当します。

schemes

APIの通信プロトコルを記載する欄です。http, https, ws, wss の中から使用するプロトコルを記入してください。

paths

basePathに続くAPIのパスを記入する欄で、必須項目となっています。

先ほど紹介したtags と紐づけて記入していくことでタグ毎にまとめられた見やすいドキュメントが作成されます。

サンプルコードを例に記入方法を見ていきましょう。

1paths:
2　/pet/findByStatus:　 #basePathに続くAPIのパス
3    get:　 #HTTP通信の種類
4      tags:
5      - "pet". #tagsで定義したタグを記入

上記以外にもパラメーターやレスポンスを記入するフィールドもあります。

securityDefinition

セキュリティーに関する定義をここに記入します。

definitions

definitionsでは他の部分で使いまわしたい内容をオブジェクトで定義することができます。

サンプルコードを一部抜粋したものも見ていきましょう。

1paths:
2  /pet:
3    post:
4#途中省略
5　schema:
6  　$ref: "#/definitions/Pet"
7definitions: 
8　Pet:
9    type: "object"
10    required:
11    - "name"
12    - "photoUrls"
13    properties:
14      id:
15        type: "integer"
16        format: "int64"
17      category:
18        $ref: "#/definitions/Category"
19      name:
20        type: "string"
21        example: "doggie"
22      photoUrls:
23        type: "array"
24        xml:
25          name: "photoUrl"
26          wrapped: true
27        items:
28          type: "string"
29      tags:
30        type: "array"
31        xml:
32          name: "tag"
33          wrapped: true
34        items:
35          $ref: "#/definitions/Tag"
36      status:
37        type: "string"
38        description: "pet status in the store"
39        enum:
40        - "available"
41        - "pending"
42        - "sold"
43    xml:
44      name: "Pet"

ここではpathのschemeの部分で $ref: を使用することでdefinitionsで定義した Pet の内容を流用しています。

またdefinitionsで定義した内容はドキュメントにも Model という欄に記載されます。

externalDocs

ここでは外部リンクを定義します。

クリックして欲しい文字と該当URLを記入することでリンクを作成することができます。

終わりに

Swagger Editer について見ていきました。これでAPIドキュメントの作り方がざっくり分かったかと思います。

今回Swaggerで作成したAPIドキュメントをPDF化したいということもあるかと思います。

その方法は次回書いていきたいと思いますので楽しみにしておいてください(笑)。