テックブログ

  1. tool
  2. 368 view

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

「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について知りたい方はぜひご覧くださいー。

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(ウィンディ)ではAPIドキュメントの作成を代行できます!API仕様書の作成、管理、更新でお困りの方はぜひ下記をご覧ください!!

The following two tabs change content below.

riri

半年おきくらいにバックエンドとフロントエンドを行ったり来たり。 25歳。 将棋好き。

toolの最近記事

  1. WordPressサイトのアクセス解析をスマホでみる方法

  2. エンジニア、ブロガーに超オススメなChrome拡張機能11選

  3. ランディングページ(LP)を5分で作る【ペライチ】

  4. macでgifを撮るのに便利【GIPHY Capture】

  5. Swagger UI + Swagger Editorを使ってAPI仕様書作成を効率化する…

関連記事

コメント

  1. この記事へのコメントはありません。

  1. この記事へのトラックバックはありません。