Swaggerを使う
Swagger を使ってみました。
API を実装する際に、必須では無いのですが、仕様を明確にしていく事が後々役に立つと思います。
swagger の定義を見るだけでなく、自分で作成・編集する事を念頭においています。
- Node.js のインストール(既にあれば不要)
- GitHub のインストール(既にあれば不要)
- Swagger-Editor のインストール
だけで良いです。
Swagger-UI(定義を参照するだけ)や、swagger-node(Node.js でRESTFulサービスを作る)は不要です。
Node.js や GitHub のインストールはここでは解説しません。
Swagger-Editor のインストール
GitHub から取得して、npm でインストールするだけです。
git clone https://github.com/swagger-api/swagger-editor.git
cd swagger-editor
npm install
npm start最後の npm start で Node.js の WEBサーバーを起動しています。
デフォルトだと、ローカルホストの 3001番ポートで待ち受けします。(変更も可能)
ブラウザで、http://localhost:3001/ でアクセスすれば、Swagger-Editor が現れます。
この状態では、サンプルの仮想のペットショップの仕様が例示されているので、
これを参考にして、自分の作りたい API の仕様を書いていきます。
Swagger-Editor 自体が SPA ですので、実は Node.js も不要なのですが、ローカルで常時WEBサーバーを
起動している人は少ないと思われますので一般的にはこのような手順が紹介されています。
Swagger-Editor を使う
定義したものはファイルとして保管します。
形式は２つありますが、普通は YAML 形式を使うと思います。(もう１つは JSON形式)
要するに、このファイルを書くことが定義をする目的になります。だったら「メモ帳」でもいいじゃない？と言われればその通りです。
Swagger Editor を使えば、文法をチェックしてくれます。慣れてくればチェックだけさせても良いです。
また、正直 Swagger の書式で書くのは面倒です。Excel で書いたほうが簡単で読みやすいとも思います。
でも、Swagger で書けば、
- 他人にも間違いなく仕様を正確に伝える事ができる
- 実際に動作する環境に対して Swagger からテストする事ができる
のメリットが大きいです。
さて、「使い方」と言っても一つ一つのキーワード(フィールド名)の意味を解説しても仕方ないと思いますので、ここでは要点のみ記載します。
フィールド名（予約語）なのか任意の名前なのかが最初は解かり難いのが難点で、しかもインデントの階層が深くなるので、それも解かり難さの原因になっています。
フィールド名に続く要素が、配列(先頭に"-")なのかハッシュ(無印)なのかを区別すると比較的理解し易いと感じました。
以下は、先頭から良く使う記述です。フィールド名は太字にしています。
# 記載した openapi のバージョンに合わせて文法チェックが行われる
openapi: 3.0.3
info:
title: 作成するサービスの名前
version: 1.0.0
# 実際に API が配備されている URL (配列)
servers:
- url: 'https://hogehoge.co.jp/api/v1'
# API エンドポイント(ハッシュ)
paths:
/user/search:
# メソッド(ハッシュ)
get: # put/post/delete
summary: "タイトル"
description: "説明"
# パラメータ(配列)
parameters:
- name: "address" # "パラメータ名
in: "query" # "?"以降。"path" とするとURLの中に含まれる
description: "項目の説明"
required: false # 必須なら true
schema: # ver3.x から階層記述になった(ハッシュ)
type: "string" # 型 "integer" 等
# 応答(ハッシュ)
responses:
"200": # ステータスごと(ハッシュ)
description: 'OK'
content:
application/json:
# 返す値(全てハッシュ)
schema:
type: object
properties: # object の場合
records: # 要素の名前
type: array
items: # arrayの場合
type: object
properties:
id:
type: integer
example: 1234
name:
type: string
example: "名称"
| « 前頁 | 次頁 » |