SwaggerでAPIドキュメントを作成する
2022.04.05
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のversion。 |
| info（必須） | APIの概要。バージョンや内容の説明を書く。 |
| host | API通信を行うサーバーのホスト名。 |
| basePath | 上記のホスト以降のパス。 ”/” で描き始める。 |
| tags | タグの名前及びその説明。 |
| schemes | APIの通信プロトコル。基本的には"https"を記載。 |
| paths（必須） | 提供するAPIのパス。 |
| securityDefinitions | セキュリティ、認証の定義を記載。 |
| definitions | レスポンスやパラメータに使用するデータの定義。 |
| externalDocs | 外部リンクを定義するところ。 |
swagger
必須項目となっているswagger。ここには使用するswaggerのバージョンを記述します。
特に理由がなければ標準の2.0のままでOKです。
info
infoも必須項目です。APIの概要を説明するためのものです。内容は下記の表参照。
| フィールド名 | 内容 |
| description | APIの概要を説明するところ。 |
| version | APIのバージョンを説明するところ。 |
| title | APIの名前、タイトル。 |
| contact | APIについての問い合わせ先を記入。 |
| termsOfService | 利用規約を記入。 |
| lisence | 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 と紐づけて記入していくことでタグ毎にまとめられた見やすいドキュメントが作成されます。
サンプルコードを例に記入方法を見ていきましょう。
1 2 3 4 5 | paths: /pet/findByStatus: #basePathに続くAPIのパス get: #HTTP通信の種類 tags: - "pet". #tagsで定義したタグを記入 |
上記以外にもパラメーターやレスポンスを記入するフィールドもあります。
securityDefinition
セキュリティーに関する定義をここに記入します。
definitions
definitionsでは他の部分で使いまわしたい内容をオブジェクトで定義することができます。
サンプルコードを一部抜粋したものも見ていきましょう。
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 | paths: /pet: post: #途中省略 schema: $ref: "#/definitions/Pet" definitions: Pet: type: "object" required: - "name" - "photoUrls" properties: id: type: "integer" format: "int64" category: $ref: "#/definitions/Category" name: type: "string" example: "doggie" photoUrls: type: "array" xml: name: "photoUrl" wrapped: true items: type: "string" tags: type: "array" xml: name: "tag" wrapped: true items: $ref: "#/definitions/Tag" status: type: "string" description: "pet status in the store" enum: - "available" - "pending" - "sold" xml: name: "Pet" |
ここではpathのschemeの部分で $ref: を使用することでdefinitionsで定義した Pet の内容を流用しています。
またdefinitionsで定義した内容はドキュメントにも Model という欄に記載されます。
externalDocs
ここでは外部リンクを定義します。
クリックして欲しい文字と該当URLを記入することでリンクを作成することができます。
終わりに
Swagger Editer について見ていきました。これでAPIドキュメントの作り方がざっくり分かったかと思います。
今回Swaggerで作成したAPIドキュメントをPDF化したいということもあるかと思います。
その方法は次回書いていきたいと思いますので楽しみにしておいてください(笑)。
書いた人はこんな人
IT技術6月 6, 2023encoding.jsを使ってJavaScriptで文字コードを変換する- IT技術1月 19, 2023Laravelでboolean型にしたはずのデータがint型で返ってくる
- IT技術10月 17, 2022メンターをやってみて逆に学んだこと
- IT技術7月 1, 2022Swaggerで作成したAPIドキュメントをPDF化
関連記事
採用情報
\ あの有名サービスに参画!? /
バックエンドエンジニア
\ クリエイティブの最前線 /
フロントエンドエンジニア
\ 世界を変える…！ /
Androidエンジニア
\ みんなが使うアプリを創る /
iOSエンジニア
