Swagger UI + Swagger Editorを使ってAPI仕様書作成を効率化する【Docker】

ツール紹介
17339 view

Swagger UI + Swagger Editorを使ってAPI仕様書作成を効率化する【Docker】

最終更新日:2019/03/29

「API仕様書を書かねば、、、、」
サンプルコード
Swaggerとは
Swaggerを強力にサポートしてくれる者たち
Dockerを使ってSwaggerドキュメントを管理する
- - WINDII
  - 最新記事 by WINDII (全て見る)

「API仕様書を書かねば、、、、」

誰もがそう思っていたのだった。

そんな思いとは裏腹に、迫りくる納期、限られたリソース、誰かが作ってくれるだろうという淡い期待。

こうしてAPI仕様書は幻と化したのだった。。。 （完）

、、、ということにはならないようにSwaggerを使ってAPI仕様書を効率よく管理するお話です。

サンプルコード

すぐに試してみたい方はこちらから

Swaggerとは

SwaggerとはRESTful APIを効率よく記述するためのオープンソースフレームワークです。

2015年11月にマイクロソフトやグーグルなどによって結成されたOAI(Open API Initiative)という団体によって採用され標準化が進められています。

Swagger SpecというSwagger の仕様に準じたドキュメント形式で記述でき、Swagger EditorというSwagger Specを記述するために開発されたエディタがサポートされていたり、Swagger UIというSwagger Spec で記載された設計書をもとにドキュメントをHTML形式で自動生成してくれるツールがあったりとAPI仕様書を効率よく作成するための周辺ツールも豊富なのが特徴です。

Swaggerを強力にサポートしてくれる者たち

先ほどお話ししたように、Swaggerの強みはとにかく周辺ツールが充実していることです。いくつがご紹介します。

Swagger Spec

Swagger Spec はSwaggerの書式で記述した仕様書です。JSON形式もしくはYAML形式で記述されます。

Swagger Specの例（この場合はYAML）

openapi: 3.0.0
info:
  version: 1.0.0
  title: Swagger Petstore
  description: >-
    A sample API that uses a petstore as an example to demonstrate features in
    the OpenAPI 3.0 specification
  termsOfService: 'http://swagger.io/terms/'
  contact:
    name: Swagger API Team
    email: [email protected]
    url: 'http://swagger.io'
  license:
    name: Apache 2.0
    url: 'https://www.apache.org/licenses/LICENSE-2.0.html'
servers:
  - url: 'http://petstore.swagger.io/api'
paths:
  /pets:
    get:
      description: >
        Returns all pets from the system that the user has access to ...
      operationId: findPets
      parameters:
        - name: tags
          in: query
          description: tags to filter by
          required: false
          style: form
          schema:
            type: array
            items:
              type: string
        - name: limit
          in: query
          description: maximum number of results to return
          required: false
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: pet response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

YAMLの仕様や書き方については以下の記事にまとめたのでYAMLについて知りたい方はぜひご覧くださいー。

なんとなく使っていませんか？？YAMLの基本をまとめました！

はじめにRuby On RailsやLaravelなどモダンなWebフレームワークや、Dockerなどのインフラを触ると必ず出てくるYAML(ヤメル、ヤムル）。どこにでもいる上に、JSONやXMLを理解している人ならなんとなく理解できてしまうため、YAMLをよく使うけど、実はよくわかっていな...

Swagger Editor

Swagger EditorはSwagger Specを編集するためのツールです。
プレビュー機能が強力で編集しながら生成されるドキュメントを常に確認できるのがありがたいです！

(サンプルコードをRead meの通り立ち上げた場合
http://localhost:8001 で見ることができます！）

Swagger UI

(サンプルコードをRead meの通り立ち上げた場合
http://localhost:8002 で見ることができます！）

Dockerを使ってSwaggerドキュメントを管理する

それでは、サンプルの説明です。

とはいっても、とても簡単で、　document/openapi.yaml　をSwagger Specにしたがって記述していくだけです。

docker-compose.yamlの設定は以下のようになっています。

swagger-editor:
  image: swaggerapi/swagger-editor
  container_name: "swagger-editor"
  ports:
    - "8001:8000"

swagger-ui:
  image: swaggerapi/swagger-ui
  container_name: "swagger-ui"
  ports:
    - "8002:8000"
  volumes:
    - ./document/openapi.yaml:/openapi.yaml
  environment:
    SWAGGER_JSON: /openapi.yaml
    # API_URL: ""

swagger-api:
  image: danielgtaylor/apisprout
  container_name: "swagger-api"
  ports:
    - "8003:8000"
  volumes:
    - ./document/openapi.yaml:/openapi.yaml
  command: /openapi.yaml

docker-compose up -d

で立ち上げると

http://localhost:8001 でswagger-editor
http://localhost:8002 でswagger-ui
http://localhost:8003 でapisprout
が起動するように設定してあります。（この辺はこちらをもとに設定しました）

swagger-editor、swagger-uiの説明はすでにしたのでここでapisproutの説明をしておきます。apisproutはswaggerからモックサーバを立ち上げてくれるツールでリクエストを投げるとモックデータを返してくれます。例えば以下のような感じです。

以上でSwaggerの紹介でした。API仕様書を書くのはなかなか骨が折れる作業ですが、例えリソースの足りないベンチャーでもAPI仕様書だけは死守したいところ。ぜひSwaggerの導入を検討してみてください！

この記事を書いた人
最新の記事

WINDII

WINDII（ウィンディ）は、フリーランスエンジニアが運営するテックメディアです。日々の業務で得た知見を、皆さんに役立つコンテンツにして発信していくので応援よろしくお願いします！また、Slackで無料コミュニティも運営しています。たくさんのエンジニアが参加していて、プログラミングの相談や雑談などをしている楽しいコミュニティなので、興味ある方はぜひお気軽にご参加ください。 Slackコミュニティはこちらから

現役フリーランスエンジニアが運営するテックメディア。日々の業務で得た知識を発信していきます！

WINDIIテック