stoplight.ioを使ってみよう
こんにちは。エンジニアの島袋です。 先週末「君の名は」を見てきました。 おもしろかったです。(小学生並みの感想)
今回はstoplight.ioというwebサービスについて紹介します。
TL;DR
- stoplight.ioを利用すると
- swagger-specの作成がめちゃくちゃ捗る
本題に入る前に、swaggerについて
Swaggerとは
swaggerは大雑把にいうと、REST APIを仕様を記述するためのツール群です。 swaggerについては以下のスライドが詳しいです。
このswagger、何が嬉しいかといいますと、apiのレスポンスがswaggerで記述した仕様(swagger-spec)に準拠しているか検査できるんですね。
これを目視、手動でやるとか正直考えたくないです。
(筆者は前職で手動でやってました)
そもそもREST APIに仕様書いるのかっていう話なんですが、まあ必要ですよね。
API実装を外注に出す場合、あるいはこちらがAPIの実装を受託する場合など、特に必須になると思います。
その他、自社サービスのAPIをサードパーティ向けに公開する場合なども必要になってくるでしょう。
また、swagger-specはswagger-uiで人間が読むためのドキュメントとして表示できることも嬉しいポイントです。
(swagger-ui立ち上げるのが面倒くさい場合はbootprint-swaggerで静的htmlに落とします)
Swaggerのつらいところ
そんな便利なswaggerなんですが、swagger-specを記述するのはかなり大変です。
swagger-specはjsonかyamlで記述するのですが、レスポンス項目が5つしかない簡単なサンプルでも以下のような分量になります。
swagger: '2.0'
info:
version: ''
title: MySample
description: sample for cloud blog
host: 'localhost:9944'
basePath: /api
schemes:
- http
paths:
'/student/{student_id}':
parameters:
- name: student_id
in: path
required: true
type: string
get:
operationId: GET_student-student_id
produces:
- application/json
responses:
'200':
description: ''
schema:
type: object
properties:
student_id:
type: string
grade:
type: integer
minimum: 1
maximum: 6
first_name:
type: string
minLength: 1
maxLength: 20
last_name:
type: string
minLength: 1
maxLength: 20
hobbies:
type: array
items:
type: string
minLength: 1
maxLength: 100
required:
- student_id
- grade
- first_name
- last_name
- hobbies
examples:
application/json:
student_id: aliqua sint proident nostrud
grade: 3
first_name: id consect
last_name: magna mol
hobbies:
- dolore Lorem ut elit dolor
- ad nisi amet adipisicing
- ipsum aliqua
- consequat sunt
definitions: {}
はい。つらいですね。
それを解消できるサービスがstoplight.ioです。
stoplight.ioについて
stoplight.ioは簡単にいうと、REST APIをブラウザ上でモデリングし、swagger-specとしてエクスポートすることが可能なサービスです。
(ブラウザ上といいましたが、デスクトップアプリも提供されています。(恐らくElectron製))
個人で利用する分には無料のようなので、とりあえず使ってみましょう。
githubアカウントでもサインアップ可能です。
stoplightで簡単なAPIエンドポイントを作成してみる
上記で貼り付けたyamlの内容と同じものをstoplightで作成してみます。
/student/{student_id}にGETリクエストを投げると、該当する学生の情報をjsonで返却するものとします。
返却項目は以下とします。
- student_id : 学生番号(必須, 文字列)
- grade : 学年(必須, 数値1〜6の間)
- first_name : 名(必須, 文字列, 1文字以上、20文字以内)
- last_name : 姓(必須, 文字列, 1文字以上、20文字以内)
- hobbies : 趣味(必須, 文字列配列, 無い場合は空の配列, 要素は1文字以上、100文字以内)
まず、ダッシュボード画面から、New Endpointを選択します。
http methodや、endpointのパスなどの入力欄が表示されますので、下図のように入力します。
次にレスポンス項目を設定していきます。
画面を下にスクロールしていくと、Responsesという項目があるので、そちらでレスポンス項目の設定を行っていきます。
「object」の横の+をクリックすると、レスポンス項目を追加していくことができます。
各レスポンス項目左側がプロパティ名、右側がプロパティの型となります。
プロパティ名は当然自分で入力する必要がありますが、型についてはjson-schemaで定義されている型が下図のように選択肢としてポップアップするので、そこから選択することができます。
response項目にはバリデーション設定を加えることができます。
右端にあるvalidationsとrequiredというチェックボックスを見てください。
requiredにチェックを入れると、その項目は必須返却項目となります。
validationsをクリックすると、詳細なバリデーション設定項目が表示されます。
ここでは返却値の文字数制限(最小、最大)や、返却値の文字種の制限(正規表現)などの設定が可能です。
一通り入力し終えたら、JSON Schemaタブを開いてみます。
JSON Schemaタブにはeditorタブで入力した内容がJSON Schemaに変換されたjsonが表示されます。 どうでしょうか？
swagger-editorではここで表示されている内容を自分で入力する必要がありましたが、stoplightのeditorでは非常に簡単に入力することができたと思います。
次にexampleタブを開いてみます 。 最初は何も表示されていないと思います。
GENERATE EXAMPLE FROM SCHEMAをクリックしてみてください。
レスポンスのサンプルが表示されるはずです。
ここでGENERATE SCHEMA FROM EXAMPLEを押下すると、レスポンスサンプルからjson schemaが出力されます。
(なのでクリックしないでください。)
逆にいうと、「こんな感じの出力が欲しい」というサンプルをベースに仕様を起こすことが可能ということです。
ここまで完了したら、画面上部にあるsaveをクリックし、エンドポイントの作成を保存します。
最後にyamlでswagger-specとしてエクスポートしてみます。
画面右上のexportをクリックしてください。
エクスポート形式が復数表示されるので、ここでは
OAS(Swagger 2).yamlを選択します。
するとブラウザの別タブが開き、yaml形式のswagger-specが表示されますので、右クリックから別名で保存でファイルに保存します。
stoplight.io便利なので使いましょう
如何でしたでしょうか？(大分雑な説明でしたが)
エクスポートしたyamlファイルの長さを見ると、swagger-editorで記述するのと比較し、stoplightでモデリングを行うのがとても楽だというのが分かると思います。
今回はstoplightのモデリング機能に絞って紹介しましたので、次回はstoplightのmock機能について紹介したいと思います。
(いつになるかわかりませんが)
のSalesforce/Force.com
