« 2016年7月 | メイン | 2016年12月 »

2016年10月

2016年10月24日 (月)

stoplight.ioを使ってみよう

こんにちは。エンジニアの島袋です。 先週末「君の名は」を見てきました。 おもしろかったです。(小学生並みの感想)

今回はstoplight.ioというwebサービスについて紹介します。

TL;DR

  • stoplight.ioを利用すると
  • swagger-specの作成がめちゃくちゃ捗る

本題に入る前に、swaggerについて

Swaggerとは

swaggerは大雑把にいうと、REST APIを仕様を記述するためのツール群です。 swaggerについては以下のスライドが詳しいです。

Swaggerで始めるモデルファーストなAPI開発

この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文字以内)

Stoplight_dashboard


まず、ダッシュボード画面から、New Endpointを選択します。

http methodや、endpointのパスなどの入力欄が表示されますので、下図のように入力します。

Endpoint_basic


次にレスポンス項目を設定していきます。

画面を下にスクロールしていくと、Responsesという項目があるので、そちらでレスポンス項目の設定を行っていきます。

「object」の横の+をクリックすると、レスポンス項目を追加していくことができます。

各レスポンス項目左側がプロパティ名、右側がプロパティの型となります。

プロパティ名は当然自分で入力する必要がありますが、型についてはjson-schemaで定義されている型が下図のように選択肢としてポップアップするので、そこから選択することができます。

Type_select


response項目にはバリデーション設定を加えることができます。

右端にあるvalidationsとrequiredというチェックボックスを見てください。

requiredにチェックを入れると、その項目は必須返却項目となります。

validationsをクリックすると、詳細なバリデーション設定項目が表示されます。

ここでは返却値の文字数制限(最小、最大)や、返却値の文字種の制限(正規表現)などの設定が可能です。

Validations_2


一通り入力し終えたら、JSON Schemaタブを開いてみます。

JSON Schemaタブにはeditorタブで入力した内容がJSON Schemaに変換されたjsonが表示されます。 どうでしょうか?

swagger-editorではここで表示されている内容を自分で入力する必要がありましたが、stoplightのeditorでは非常に簡単に入力することができたと思います。

Response_json_schema


次にexampleタブを開いてみます 。 最初は何も表示されていないと思います。

GENERATE EXAMPLE FROM SCHEMAをクリックしてみてください。

レスポンスのサンプルが表示されるはずです。

ここでGENERATE SCHEMA FROM EXAMPLEを押下すると、レスポンスサンプルからjson schemaが出力されます。

(なのでクリックしないでください。)

逆にいうと、「こんな感じの出力が欲しい」というサンプルをベースに仕様を起こすことが可能ということです。

Responses_example


ここまで完了したら、画面上部にあるsaveをクリックし、エンドポイントの作成を保存します。

最後にyamlでswagger-specとしてエクスポートしてみます。

画面右上のexportをクリックしてください。

エクスポート形式が復数表示されるので、ここでは

OAS(Swagger 2).yamlを選択します。

Export_select


するとブラウザの別タブが開き、yaml形式のswagger-specが表示されますので、右クリックから別名で保存でファイルに保存します。

stoplight.io便利なので使いましょう

如何でしたでしょうか?(大分雑な説明でしたが)

エクスポートしたyamlファイルの長さを見ると、swagger-editorで記述するのと比較し、stoplightでモデリングを行うのがとても楽だというのが分かると思います。

今回はstoplightのモデリング機能に絞って紹介しましたので、次回はstoplightのmock機能について紹介したいと思います。

(いつになるかわかりませんが)

採用情報

株式会社フレクトでは、事業拡大のため、
・Salesforce/Force.comのアプリケーション開発
・HerokuやAWSなどのクラウドプラットフォーム上での
Webアプリケーション開発
エンジニア、マネージャーを募集中です。

未経験でも、これからクラウドをやってみたい方、
是非ご応募下さい。

フレクト採用ページへ

会社紹介

株式会社フレクトは、
認定コンサルタント
認定上級デベロッパー
認定デベロッパー
が在籍している、セールスフォースパートナーです。
また、heroku partnersにも登録されています。
herokuパートナー
株式会社フレクトのSalesforce/Force.com
導入支援サービス
弊社の認定プロフェッショナルが支援致します。
・Visualforce/Apexによるアプリ開発
・Salesforceと連携するWebアプリ開発
も承っております。
セールスフォースご検討の際は、
お気軽にお問合せください。

2017年10月

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        
ブログ powered by TypePad