48
42

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

More than 5 years have passed since last update.

Swaggerとswagger-node

Last updated at Posted at 2016-09-17

##Swaggerとは
SwaggerとはREST APIのドキュメント記載に関するフォーマット仕様と、周辺ツールを指します。現在v2.0。(あと、Swagger v2.0がそのままOpen Api v2.0というのになったらしく、次のv3.0の議論はOpenAPI.nextブランチで行われているようです。)
OAI/OpenAPI-Specification: The OpenAPI Specification Repository
OAI/OpenAPI-Specification at OpenAPI.next

以下の記事が詳しいです。

swagger introduction - Qiita
API Meetup Tokyo #15 〜OpenAPI Specification (Swagger) レポート | NTT Communications Developer Portal

Swaggerのサイトには、Swagger用のツールが公開されています。

  • Swagger Editor
  • Swagger UI
  • Swagger Codegen
  • Swagger Core

Swaggerで書かれたSwagger.yamlから、ドキュメントを生成したり、apiを試せるUIを出したり、テストコードを生成したり、モックサーバーを立てたり、フロントとサーバーのコード生成等々といったことが出来ます。

しかしドキュメントによるとツール群はビルドが必要だったり、ローカルにインストールしたり、一部をWebフレームワーク側に持って行く必要があったり難しそう。

と思ってましたが、npmにあるswagger-nodeを使うと、あらかた入っているのですぐにSwaggerを導入した開発環境を体験できそうです。

##Node環境でSwagger

swagger-nodeとは、Swaggerを使った開発ができるようにする環境みたいなかんじです。

swagger用のフレームワークのようなものを入れたプロジェクトの作成や、起動が出来ます。Swagger-toolsも入っています。
swagger-node
swagger-nodeのドキュメント

###インストール

npm install -g swagger

インストールはしばらくかかります。
インストールするとswaggerコマンドが使えるようになります。

以下一通り試してみます。

###1.Swaggerプロジェクトを作る。

swagger関連のモジュールを入れた、webプロジェクトをつくります。

swagger project create my-project

この時、Express、Hapi、Restify、Sailsといったフレームワークの中から使うものを選べます。

作られるプロジェクトは、nodeに選んだフレームワークと、swagger用のミドルウェアを設定したものです。Swagger.yamlファイルを使ってバリデーションやルーティングを行います。

# binds a127 app logic to a route
x-swagger-router-controller: hello_world

###2.プロジェクトを起動する。

プロジェクトを起動してみます。この状態でソースコードの変更すると再起動してくれます。

swagger project start my-project

プロジェクトに最初から用意されているコードでは/helloというアドレスに、パラメータ名nameで文字列を渡すとjsonを返すapiが定義されているので、
以下の様なcurlを打つと結果が帰ってくるようになっています。

curl http://127.0.0.1:10010/hello?name=Scott

###3.apiのドキュメントをブラウザで見る。

swagger-uiを使って、apiをブラウザで確認してみます。

app.jsを編集して一行追加します。

  swaggerExpress.register(app);
  var port = process.env.PORT || 10010;

  app.use(swaggerExpress.runner.swaggerTools.swaggerUi());    //追記

  app.listen(port);

そして起動して、http://localhost:10010/docs/ にブラウザでアクセスするとswagger-ui画面になっています。

この画面でapiを試すことが出来ます。

画面のdefaultをクリックして、apiの欄をクリックすると、下の方にnameという項目がありその下にTry it outというボタンがあります。
必要があればパラメータを設定したあとにボタンを押すと、レスポンスの結果が表示されます。

###4.Swagger.yamlを編集する。

Swagger.yamlファイルを編集してみます。以下のコマンドを打ちます。

swagger project edit my-project

そうするとswagger-editorが立ち上がります。ドキュメントを確認しながら編集できます。

Swaggerファイルの編集方法は下記のページが参考になりました。
swaggerの基礎。swaggerの設定ファイルの書き方とか - Qiita

Tutorial
Writing OpenAPI (Swagger) Specification Tutorial – Part 1 – Introduction | API Handyman

Open APIのサンプルファイル。
OpenAPI-Specification/examples/v2.0/yaml at master · OAI/OpenAPI-Specification

###5.Mockモードで起動する。

Swagger.yamlファイルに書いたapiの仕様に基づいて、適当な値を返すモックサーバーに出来ます。

モックモードでの起動は、./config/default.yamlで設定するか、
swagger project startコマンドにオプションを付けて起動する方法があります。

試すために、Swagger.yamlファイルに新しいapiを書いてみます。
/taskというアドレスにgetするとidと文字列のjsonが返るというapiを書き足しました。

...
/task:
  x-swagger-router-controller: hello_world
  get:
    description: task api
    operationId: task
    responses:
      "200":
        description: success
        schema:
            type: "object"
            properties:
              id:
                type: "integer"
                format: "int64"
              task:
                type: "string"

そして以下のコマンドでサーバーを起動します。-mがモックモード指定です。

swagger project start -m

そのあと、http://localhost:10010/docs/ にアクセスして、/taskというapiを叩いてみます。
すると、以下のような結果が帰ってきます。

{
  "id": 1,
  "task": "Sample text"
}

コントローラの実装を行っていないのに、値が帰ってきました。
さらにモックモードでは細かいカスタマイズが可能です。(api/mocksフォルダのcontrollerを使うようにするなど)

###6.testコードのテンプレート

最後に、(ドキュメントに見当たらないけど)テストコードのテンプレートの生成と、実行コマンドがあるようです。

swagger project generate-test

上記でtest/api/clientフォルダにtestコードのテンプレートが生成されます。ここにテストを書いていくと実行コマンドで実行できるのかな?。

swagger project test

##とりあえずここまでで、まとめ

swagger.yaml一つでいろいろ済むショートカット感がすごい。モックサーバーだけ使うのもありかもしれない。認証とかになると難しいのかもしれない。既存のプロジェクトをswagger化する仕方とか、Node以外の環境とか、まだいろいろわからない。
以下の様な記事も見かけました。
Speed up your RESTful API development in Node.js with Swagger | Scotch

48
42
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
48
42

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?