logo-sm

お電話はこちら 03-6912-0139

ブログ

REST APIドキュメントをReDocを使って作成するための導入手順。

2020.01.29

APIドキュメントを作るにあたり、なんとも簡単かつ綺麗にかける方法がないだろうか(今更!?)と思い調査していると、
ReDocなるツールを見つけたのでインストールから静的コンテンツによるドキュメント作成までの手順をこちらに記載しておきます。

前提としてはMacでパッケージマネージャとしてyarnが導入されていることになります。
npmでも良いのですが、今回はyarnにしています。
ここは好みと、実際の導入環境によると思います。
なおnpmコマンドのインストールコマンドに読み替えて頂ければインストール可能だと思います。

今回はyarnを使ってグローバルではなく、ローカルにインストールしますのでnpxコマンドが必要となります。

0.npxコマンドが使えるかの確認

$ npm -v
6.4.1 ← 5.2.0以上にバンドルされているので大丈夫

1.redoc、redoc-cliをインストールする。

$ mkdir redoc.sample  
$ cd redoc.sample  
$ yarn add redoc  ← redocのインストール
$ yarn add redoc-cli  ← redoc-cliのインストール
$ yarn list redoc  ← 入ったかを確認する。
warning package.json: No license field
warning No license field
warning Filtering by arguments is deprecated. Please use the pattern option instead.
├─ redoc-cli@0.9.5
│  └─ redoc@2.0.0-rc.21
└─ redoc@2.0.0-rc.20
✨  Done in 0.24s.

2.redoc-cliでドキュメントを作成してみる

APIドキュメントの元となるswagger.yamlは以下を参考に記述します。
petstore.yaml

petstore.yamlを参考にして、redoc.sampleの真下にswagger.yamlを作成してみましょう。

$ pwd
redoc.sample
$ ls swagger.yaml
swagger.yaml

そしてお待ちかねのhtmlファイルとして、APIドキュメントを作成してみましょう。

$ npx redoc-cli bundle swagger.yml -o index.html
[ReDoc Compatibility mode]: Converting OpenAPI 2.0 to OpenAPI 3.0
Prerendering docs

� bundled successfully in: aaa/index.html (1059 KiB) [⏱ 0.479s]

出力されたindex.htmlをブラウザで見ると整形されたAPIドキュメントが出来上がっております。綺麗!!

あとswagger.ymlをredoc-cliの機能でローカルサーバーを立ち上げてhttp経由でも見ることができます。

$ npx redoc-cli serve swagger.yml --watch
{ ssr: undefined,
  watch: true,
  templateFileName: undefined,
  templateOptions: {},
  redocOptions: {} }
[ReDoc Compatibility mode]: Converting OpenAPI 2.0 to OpenAPI 3.0

Server started: http://127.0.0.1:8080
�  Watching redoc.sample..../ for changes...

ここまできてhttp://127.0.0.1:8080をブラウザで見るとちゃんとみれます。
–watchオプションをつけることでswagger.ymlを編集してブラウザをリロードすると、変更箇所が反映しています。

気持ちよくかけることは、ドキュメントを書く側に取っては精神衛生上嬉しいですね!!

関連記事

  • Vue.jsを使用するための優れたUIフレームワークを紹介する
    はじめに こんにちは、クロスメディア課のベトナム人エンジニア ティエンです。 9月に入ってから急激に寒くなりま […]

    2020.10.13

  • CloudFront+S3+Route53以外のドメイン管理でSPAをSSL化する
    はじめに こんにちは。 季節はそろそろ梅雨も明けて初夏の装いに差し掛かっておりますが、いかがお過ごしでしょうか […]

    2020.07.09

  • UnityプロジェクトをGitHubとSourcetreeで管理する【導入編】

    2020.05.25

  • パートナー

  • 人材育成