Qiita Teams that are logged in
You are not logged in to any team

Log in to Qiita Team
Community
OrganizationEventAdvent CalendarQiitadon (β)
Service
Qiita JobsQiita ZineQiita Blog
38
Help us understand the problem. What is going on with this article?

More than 1 year has passed since last update.

@godgarden

[Swagger] OpenAPI3.0で記述したAPI仕様書をHTMLとして出力する

Intro

SwaggerUI を利用すると、OpenAPIで記述したAPI仕様書をHTTPサーバーとしてインターネットに公開したり、または ローカルにHTTPサーバーとして起動して確認できます。

チームで開発する場合、同じドキュメントを不特定多数のメンバーと共有して開発したくなるユースケースが発生することがあると思います。

SwaggerUIDocker Image をサーバーとして起動させ配信したりする方法もありますが、何らかの社内の事情で使えない場合や、もう少し簡単に始めたい場合に、HTMLファイルとして出力し、ブラウザで確認するというアプローチもあります。

HTMLに変換してブラウザで確認する

OpenAPIで記述したファイルから、洗練されたスタイルが適用されたHTMLファイルにしてブラウザに確認するアプローチとしていくつかあります。

以下のファイルを参考にそれぞれドキュメントを生成してみます。

openapi.yaml
openapi: 3.0.0
info:
  version: 1.0.0
  title: Swagger sample
paths:
  /users:
    get:
      summary: Usersを取得するAPIです。
      responses:
        '200':
          description: HTTPステータスコード200と以下の情報を含むJSONオブジェクトを返します。
          content:
            application/json:
              schema:
                type: object
                properties:
                  user_id:
                    type: string
                    example: 1234567

swagger-codegen

swagger-codegen をインストールし実行するとHTMLが生成されます。

$ brew install swagger-codegen
$ swagger-codegen generate -i openapi.yaml -l html -o /tmp/swagger-sample

swagger-codegen.png

swagger-ui

swagger-ui プロジェクト配下にある dist ディレクトリに必要なファイルが一式あります。

自身が作成した仕様書を表示したい場合は index.html に記述されているリンクを変更すればOKです。ディレクトリ一式をWebサーバーへアップロードすれば swagger-ui のスタイルのままドキュメントを閲覧することができます。

$ git clone git@github.com:swagger-api/swagger-ui.git
$ cd swagger-ui/dist
$ vi index.html
index.html
     window.onload = function() {
       // Begin Swagger UI call region
       const ui = SwaggerUIBundle({
-        url: "https://petstore.swagger.io/v2/swagger.json",
+        url: "https://petstore.swagger.io/v2/swagger.yaml", ← ★ここを変更する★
         dom_id: '#swagger-ui',
         deepLinking: true,
         presets: [

swagger-ui.png

ReDoc

Redocを使うとデフォルトでかっこいいドキュメントが出来上がります。
個人的には3カラムのRedocのドキュメントが好みです。redoc demo

README に書かれているように基本的にはリンクを書き換えるだけで動作します。また CLIも提供されているようです。今回はCliを使ってみます。

$ npm install -g redoc-cli
$ redoc-cli bundle openapi.yaml

redoc.png

まとめ

API仕様書を OpenAPI で記述していたら Swagger をはじめとした各種周辺ツールと簡単に連携できて良さそうです。

また、今回作成したHTMLを AmazonS3GithubPages といったサービスにホスティングさせることでAPI仕様書をインターネットに公開も簡単に出来そうですね。

関連

38
Help us understand the problem. What is going on with this article?
Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
38
Help us understand the problem. What is going on with this article?