【15分でできる】Swaggerを使って、ExpressのAPIドキュメントを作る

こんにちはMIYACHIN(@_38ch)です。

この記事では、Swaggerを使ってNode.jsのフレームワークであるExpressで作成したAPIのドキュメント(いわゆるAPI定義書)をHTMLで生成する方法を紹介していきます。

作成したAPIドキュメントでは、そのAPIに関する説明やパラメーター、レスポンスが確認できるだけでなく、ドキュメント上からAPIを試し打ちして、レスポンスを確認することもできます。

HTMLをブラウザで開くとExpress上のAPIが一覧化されます

目次

  • Swaggerとは?
  • Swagger UIをダウンロードする(1mins)
  • ExpressでサンプルAPIを作る(5mins)
  • Swagger Specを書いてドキュメント化する(5mins)
  • Swagger UIからAPIドキュメントを確認(4mins)

この記事は以下のことを前提とした記事です。

  1. PCにすでにNode.jsがインストールされている。
  2. Expressの使用経験がある。

Swaggerとは

Swaggerとは、開発設計、ビルド、ドキュメンテーション、RESTful Web serviceを支援するツールを含んだオープンソースのフレームワークです。

平たく言うと、「開発する際に便利なツールがたくさん含まれたヤツ」です。

この記事のタイトルではあえてそうしているのですが、今回ご紹介するSwagger UIはSwaggerと認知されることが多いです。

「あーあのAPIをいい感じにドキュメント化してくれるやつね」

みたいな。

しかし、実際Swaggerの提供するツールの中には、他にもSwagger EditorやSwagger Hub、Swagger Inspectorなどがあり、その中のAPI仕様を可視化するツールがSwagger UIです。

今回ご紹介するExpress(Node.js)の他にも、GO, Java, Python, Kotlin, Ruby, Scalaなどかなり多くのサーバーサイド言語をサポートしており、年々検索ボリュームが増加しているので、API仕様書としては、ExcelやPPTを除くとデファクトスタンダードと言えるんじゃないでしょうか?

Swagger UIをダウンロードする(1mins)

さて、それでは早速Swagger UIをダウンロードしていきましょう。の前に、簡単にSwagger UIが動く仕組みを図解します。

Swagger UIはExpressとは別に独立的に存在します。

それが、Expressに書かれたSwagger Specを参照し(もちろんその際にExpressが起動している必要はある)ブラウザ上でAPI仕様を可視化してくれます。

Swagger Specとは、Swagger UI上でAPI仕様を可視化できるように、API上にコメントアウトで書く、一種の記法のようなものです。Swagger Specの記法に従ってAPIのパラメータやレスポンスなどを書いておけば、それをSwagger UIがブラウザ上で綺麗に表示されてくれる訳です。

Swagger UIはGitHubレポジトリからCloneすることでダウンロードできます。

git clone https://github.com/swagger-api/swagger-ui

ダウンロードが完了したら一旦、どこかに置いておいてください。

ExpressでサンプルAPIを作る(5mins)

必要なものをインストール

mkdir swagger-express
cd swagger-express
npm install express

index.jsの作成

var express = require('express');
var app = express();
 
app.get('/user/:userId', function(req, res) {
    res.json({"user_id": 334857, "user_name": "Naruki Miyachi"});
});

//listen
app.listen(3000, function(){
    console.log("Listen on port 3000.");
});

/userにアクセスすると、あるユーザー情報を返してくれるAPIを書きました。

node index.js

でExpressを起動させて、http://localhost:3000/user にアクセスするとユーザー情報を返してくれることを確認できるはずです。

Swagger Specを書いてドキュメント化する(5mins)

それではSwagger Specを書いていきましょう。が、その前に以下の下準備を済ませておきましょう。

  1. swagger-jsのインストールと読み込み
  2. CrossOrigin問題への対応
  3. Swaggerの基本定義
  4. Swagger UI向けにJSONを返すAPIの定義

では順にやっていきます。

1. swagger-jsのインストールと読み込み

npm install swagger-jsdoc

index.jsに読み込ませます。

var swaggerJSDoc = require('swagger-jsdoc');

2. CrossOrigin問題への対応

Swagger UIからAPIを試し打ちするときに、CrossOrigin問題が発生するのでその対処を書きます。おなじくindex.jsに追記してください。

app.use(function(req, res, next) {
    res.header("Access-Control-Allow-Origin", "*");
    res.header("Access-Control-Allow-Headers", "Origin, X-Requested-With, Content-Type, Accept");
    next();
});

3. Swaggerの基本定義

これもindex.jsに追記

var options = {
    swaggerDefinition: {
        info: {
            title: 'Hello World',
            version: '1.0.0.'
        },
    },
    apis: ['./index.js'], //自ファイルを指定
};

var swaggerSpec = swaggerJSDoc(options);

4. Swagger UI向けにJSONを返すAPIの定義

index.jsに

app.get('/api-docs.json', function(req, res){
    res.setHeader('Content-Type','application/json');
    res.send(swaggerSpec);
});

Swagger UIが /api-docs.json にアクセスし、取得したJSONからAPIドキュメントを作成するようになります。

Swagger Specを書く

これをindex.jsの /user/:userId のAPIの上とかに書いてあげましょう。

/**
 * @swagger
 * /user/{userId}:
 *   get:
 *     description: Get specific user data
 *     produces:
 *       - application/json
 *     parameters:
 *       - name: user_id
 *         description: UserID to use for login.
 *         in: path
 *         required: true
 *         type: integer
 *     responses:
 *       200:
 *         description: login
 *         examples: 
 *           user:
 *              user_id: 334857
 *              user_name: Naruki Miyachi
 */

簡単に説明すると、まず、

/user/{userId} がAPIのパス。Expressとparameterの書き方が違うので注意です。{}で囲ってあげましょう。

その下には、parametersとresponsesがあります。”in”にはそのparameterがどこから取得できるかを明記します。今回は、URLのpathとしてuserId持っているのでpathと書きます。

responsesには、examplesで、レスポンスの例を書いてあげると、わかりやすくなると思います。

その他の記法については詳しくは触れませんが、このQiitaによくまとまっているので見てみてください。

Swagger UIからAPIドキュメントを確認(4mins)

さて、それでは、上記のSwagger SpecをSwagger UI上で確認していきましょう。

まずは、再度Expressを起動させます。

node index.js

port:3000でExpressが立ち上がったら、最初にダウンロードした、Swagger UIのdistフォルダの中にある、index.htmlをブラウザで開きましょう。

開いたら、画面上部のフォームに http://localhost:3000/api-docs.json と入力して、Exploreをクリック。

すると、Swagger Specで書いたAPI仕様が表示されるはずです。

Try it outをクリックすると実際にparameterを入力して、APIを試し打ちすることも可能です。

Swagger UIは実際に動いているAPIと完全に紐づいている訳ではないですが、Swagger Specをちゃんと書いてあげれば、かなりわかりやすいAPIドキュメントとして、チームに共有できるのでオススメできます。

はじめは、少しSwagger Specが書きにくいと思いますし、ググりながら書くことになると思いますが、一旦慣れてしまうと一瞬でAPI仕様をSwagger Specに落とし込むことができるようになるのでぜひ一度使ってみてください。

今回ご紹介したソースコードはここに公開しています。