RESTful APIのインターフェイスを記述フォーマットの標準化を推進する団体として
Open API Initiative (OAI) が設立されました。
OAI はAPIの記述フォーマットとして Swagger を採用しました。
- New Collaborative Project to Extend Swagger Specification for Building Connected Applications and Services - Open API Blog
- RESTful APIの記述標準化を目指す「Open API Initiative」をマイクロソフト、Google、IBMらが立ち上げ。Swaggerをベースに - Publickey
Swaggerとは？
シンプルで強力なRESTful APIの仕様記述フォーマットです。
これを利用することで、インタラクティブなドキュメントやClinet SDKの生成などを行うことができます。
このドキュメントはComputer / Human Readable なものです。
詳しくはSwagger Officialを参照
トップダウンアプローチ
Swagger Editorを利用してSwaggerの定義を作成し、Swagger Codegen toolsを利用して、
サーバーの実装を生成します。
- Swagger Editorの編集の様子
ボトムアップアプローチ
既に実装済みのRESTful API の実装があり、そこからSwaggerの定義を生成したい場合。
トップダウンアプローチと同様に手動で定義することもできるが、SwaggerをサポートしたFrameworkであれば、
Swaggerの定義を自動的に生成できます。
関連ツールの一覧は下記にあります。
Sinatra APIの生成を試行
Swagger EditorでYAMLを作成
リアルタイムで設定内容に対応するドキュメントが表示されます。
swagger: '2.0' info: title: Sample Sinatra API description: Swagger Sample for Sinatra version: 1.0.0 host: localhost:9292 schemes: - http basePath: /v1 produces: - application/json paths: /todos: get: summary: Todos description: | TODO List. parameters: - name: q in: query description: 検索条件 required: true type: string responses: '200': description: An array of todos schema: type: array items: $ref: '#/definitions/Todos' default: description: Unexpected error schema: $ref: '#/definitions/Error' definitions: Todos: type: object properties: todo_id: type: string description: 'Unique identifier for Todo.' title: type: string description: Display title of todo. description: type: string description: Description of todo. estimate: type: number description: Description of todo. Error: type: object properties: code: type: integer format: int32 message: type: string fields: type: string
Swagger EditorでSinatraのコードテンプレートを生成
こんな感じの構成で生成されます
$ tree . └── sinatra-server ├── api │ └── default_api.rb ├── config.ru ├── Gemfile ├── lib │ └── swaggering.rb ├── my_app.rb └── README.md
APIクライアントを生成します
こんな感じの構成で生成されます
$ tree . ├── lib │ ├── swagger_client │ │ ├── api │ │ │ └── default_api.rb │ │ ├── api_client.rb │ │ ├── api_error.rb │ │ ├── configuration.rb │ │ ├── models │ │ │ ├── base_object.rb │ │ │ ├── error.rb │ │ │ └── todos.rb │ │ └── version.rb │ └── swagger_client.rb └── swagger_client.gemspec
Sinatraサーバー実装
Sinagraが生成したswaggering.rbに以下のコードを追加
get "/v1/todos" do content_type :json [ { id: "1", title: "todos1", description: "desc1", estimate: 2 }, { id: "2", title: "todos2", description: "desc2", estimate: 3 } ].to_json end
サーバー起動
- gemのインストール
$ bundle
- Sinatraサーバーの起動
$ rackup
$ curl http://localhost:9292/todos
[{"id":"1","title":"todos1","description":"desc1","estimate":2},{"id":"2","title":"todos2","description":"desc2","estimate":3}]
クライントライブラリの利用
自動生成しておいたクライアントライブラリを利用してみます。
API Serverは起動したままにしておきます。
- 自動生成したRuby Clientをbuild, install
$ gem build swagger_client.gemspec find: ‘spec/*’: No such file or directory Successfully built RubyGem Name: swagger_client Version: 1.0.0 File: swagger_client-1.0.0.gem $ gem install swagger_client-1.0.0.gem Fetching: ethon-0.8.0.gem (100%) Successfully installed ethon-0.8.0 Fetching: typhoeus-0.8.0.gem (100%) Successfully installed typhoeus-0.8.0 Successfully installed swagger_client-1.0.0 Parsing documentation for ethon-0.8.0 Installing ri documentation for ethon-0.8.0 Parsing documentation for typhoeus-0.8.0 Installing ri documentation for typhoeus-0.8.0 Parsing documentation for swagger_client-1.0.0 Installing ri documentation for swagger_client-1.0.0 Done installing documentation for ethon, typhoeus, swagger_client after 3 seconds 3 gems installed
test.rb
require 'swagger_client' require 'swagger_client/api/default_api' print SwaggerClient::DefaultApi.new.todos_get({q: "test"})
- 実行結果
$ ruby test.rb [#<SwaggerClient::Todos:0x007fda9b01fef0 @title="todos1", @description="desc1", @estimate=2.0>, #<SwaggerClient::Todos:0x007fda9b01fb08 @title="todos2", @description="desc2", @estimate=3.0>]
