swagger.js で OpenAPIドキュメントをコード操作する

Swagger.js を使えば作成したOpenAPI ドキュメントが簡単にJSから操作できるようになります。

Getting Started

とりあえずSwaggerファイルからAPIを読み込んでリクエストを送ってみます。

npm i でモジュールを読み込み

$ npm i swagger-client

サンプルコードを記述。Swaggerファイルは例のペットショップAPIのサンプルを利用し、URLで記述します。

var Swagger = require('swagger-client');

var client = new Swagger({
  url: 'http://petstore.swagger.io/v2/swagger.json',
  success: function() {
    client.pet.getPetById({petId:7},{responseContentType: 'application/json'},function(pet){
      console.log('pet', pet);
    });
  }
});

node コマンドで上記ファイルを実行すると、画面上にAPIレスポンスが表示されるはずです。

client オブジェクト

client オブジェクトにはAPIコール用の様々な関数が格納されています。

各種APIはタグごとにまとまり、各タグのキーの下にoperationIdで指定した名前でAPIコール用の関数が用意されるようになっています。
(上記例ではpetタグが付けられた、operationId: getPetById のAPIをコールしている。)

parametersセクションの記述にのっとり第一引数で、入力パラメータを記述します。

内部的にはsuperagentを使用しているみたいなので、cbはそんな感じです。

ローカルファイルの読み込み

fsモジュールを使って、ローカルファイルを取り込んで食わせる事も出来るっぽいです。

var Swagger = require('swagger-client');
var fs = require('fs');

var fs = require('fs');
var text = fs.readFileSync(__dirname + '/swagger.json', 'utf-8');

var spec = JSON.parse(text);

var client = new Swagger({
    spec,
    success: function() {
        client.pet.getPetById({petId:7},{responseContentType: 'application/json'},function(pet){
            console.log('pet', pet);
        });
    }
});

Yaml でやりたければjs-yamlとか使います。

var Swagger = require('swagger-client');
var fs = require('fs');
var yaml = require("js-yaml")

var fs = require('fs');
var text = fs.readFileSync(__dirname + '/../swagger.yml', 'utf-8');

var spec = yaml.safeLoad(text);

var client = new Swagger({
    spec,
    success: function() {
        client.pet.getPetById({petId:7},{responseContentType: 'application/json'},function(pet){
            console.log('pet', pet);
        });
    }
});

ゴニョゴニョする前に内容触りたい時(ホストとか)あると思うので、そのへんが必要な場合、URL指定よりもspec指定の方が良さそう。

Promiseの利用

第一引数にusePromise: trueを渡すことでPromise形式の利用も可能。この場合、パース結果はthenクロージャの内部で受け取る形になる。

var Swagger = require('swagger-client');

new Swagger({
  url: 'http://petstore.swagger.io/v2/swagger.json',
  usePromise: true
})
.then(function(client) {
  client.pet.getPetById({petId:7})
    .then(function(pet) {
      console.log(pet.obj);
    })
    .catch(function(error) {
      console.log('Oops!  failed with message: ' + error.statusText);
    });
});

その他第一引数のパースに関しては、下記当たりのコードを見るとわかりやすそう

リクエストの発行

body パラメータは 第一引数に {body: { ... }} で送れるよう。

第二引数の リクエスト形式は省略可能。xmlとか指定したい時にはご利用下さい。