Swagger Tools で API 設計およびドキュメントを生成します。
今回は、OpenAPI 3.0 で定義してみます。

Contents

OpenAPI/Swagger

OpenAPI(Swagger) は API を記述する為の仕様です。
Swagger Specification は Linux Foundation に寄贈され、現在では OpenAPI Specification となり、OpenAPI Initiative によりプロジェクトが進められています。
Swagger 3.0 で構造もシンプルになり、より汎用性が高くなっています。

OpenAPI Initiative は Microsoft、Google、IBM、CapitalOne SmartBearなどの30以上の組織から結成されています。
SmartBear Software は Swagger の開発元であった Reverb Technologies を買収し、現在も Swagger Tooles を開発している企業です。

OpenAPI仕様

YAMLファイルで記述する際の、OpenAPI Object をみていきます。

openapi (必須)
OpenAPI仕様バージョン
info (必須)
APIに関するメタデータを表すオブジェクト
servers
ターゲットサーバーへの接続情報を表すオブジェクト
paths (必須)
APIで使用可能なパスと操作を表すオブジェクト
個々のエンドポイントとその操作への相対パス
components
仕様のさまざまなスキーマを表すオブジェクト
security
API全体で使用できるセキュリティメカニズムを表すオブジェクト
tags
追加のメタデータとともに仕様で使用されるタグを表すオブジェクト
externalDocs
追加の外部ドキュメントを表すオブジェクト

こちらを記述する為の便利なツール（Swagger Editor）がありますので、そちらを使用してみます。

Swagger Tools

クラウド上で操作できる統合環境の SwaggerHub もありますが、今回は Docker で構築してみます。

Swagger UI

Swagger UI はドキュメント化するツールです。
OpenAPI Specification 準拠の API からドキュメントを動的に生成できます。

インストール

docker でインストール

docker pull swaggerapi/swagger-ui docker run -d -p 80:8080 swaggerapi/swagger-ui

1
2

docker pull swaggerapi/swagger-ui
docker run -d -p 80:8080 swaggerapi/swagger-ui
Docker Hub
https://hub.docker.com/r/swaggerapi/swagger-ui

Swagger Editor

OpenAPI を記述できるオンラインエディタです。
ブラウザー内で YAML の OpenAPI 仕様を編集し、Swagger UI でドキュメントをリアルタイムでプレビューできます。

画面は、左側にエディター、右側に Swagger UI となっています。

インストール

docker でインストール

docker pull swaggerapi/swagger-editor docker run -d -p 80:8080 swaggerapi/swagger-editor

1
2

docker pull swaggerapi/swagger-editor
docker run -d -p 80:8080 swaggerapi/swagger-editor
80番ポートを使用したくない場合 & name 指定

docker pull swaggerapi/swagger-editor docker run -d -p 8888:80800 --name swagger-editor -it swaggerapi/swagger-editor

1
2

docker pull swaggerapi/swagger-editor
docker run -d -p 8888:80800 --name swagger-editor -it swaggerapi/swagger-editor

http://192.168.99.100:8888/
Docker Hub
https://hub.docker.com/r/swaggerapi/swagger-editor

使い方

メニューには大きく、下記があります。

File
インポートやエクスポートが行えます。
Edit
フォーマットのコンバート用のメニューです。
Insert
追加したい項目を入力フォームからエディタに挿入できます。
Generate Server
指定した言語でスタブサーバー用のソースをダウンロードできます。
Generate Client
指定した言語でクライアント用のソースをダウンロードできます。

File、Edit、Insert をさらにみていきます。

File

File メニューをみていきます。

Import URL
OpenAPI に準拠したフォーマットの URL からインポートできます。
Import file
OpenAPI に準拠したファイルからインポートできます。
Save as YAML
YAML ファイルで保存します。
Convert and save as JSON
JSON ファイルにコンバートして保存します。
Clear editor
読み込んでいるエディタをクリアします。

Edit

Edit メニューをみていきます。

Convert to YAML
YAML にコンバートします。
Convert to OpenAPI 3
Swagger 2.0 で記述視されている旧仕様から OpenAPI 3 の仕様にコンバートします。

Insert

Insert メニューをみていきます。

Add Path Item
Path の追加
summary と description も一緒に追加できます。
Add Operation
Path の Operation を追加
記述している Path と HTTP メソッドを選択して記述した内容を追加できます。
Add Info
Info の追加
既に記述している場合は、編集することができます。
Add External Documentation
外部ドキュメントを追加
Add Tag Declarations
タグ宣言を追加
Add Tags To Operation
記述している Path を選択してタグを追加できます。
Add Servers
サーバーを追加

Swagger Codegen

OpenAPI からソースコードを生成するコードジェネレータ
Swagger ドキュメントを解析して、異なる言語でクライアントコードを生成するテンプレート駆動型エンジンです。

Swagger
https://swagger.io/tools/swagger-codegen/

YAML ファイル

Swagger のサンプルにある Petstore API を参考に必須部分の YAMLを記述してみます。

openapi オブジェクト

openapi: 3.0.1

1

openapi: 3.0.1

info オブジェクト

info:
title: 雑貨店
version: 1.0.0
description: >-
雑貨店 API の概要
これはサンプルです。
license:
name: Apache 2.0
url: 'http://www.apache.org/licenses/LICENSE-2.0.html'

info:

title: 雑貨店

version: 1.0.0

description: >-

雑貨店 API の概要

これはサンプルです。

license:

name: Apache 2.0

url: 'http://www.apache.org/licenses/LICENSE-2.0.html'

paths オブジェクト

paths:
'/goods/{goodsId}':
get:
  tags:
    - goods
  summary: IDで雑貨を見つける
  description: 単一の雑貨を返します。
  operationId: getGoodsById
  parameters:
    - name: goodsId
      in: path
      description: 返す雑貨のID
      required: true
      schema:
        type: integer
        format: int64
  responses:
    '200':
      description: 成功
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Goods'
        application/xml:
          schema:
            $ref: '#/components/schemas/Goods'
    '400':
      description: 無効なIDが指定されました
      content: {}
    '404':
      description: 雑貨が見つかりません
      content: {}
  security:
    - api_key: []
post:
  tags:
    - goods
  summary: フォームデータでストア内の雑貨を更新します。
  operationId: updateGoodsWithForm
  parameters:
    - name: goodsId
      in: path
      description: 更新する必要がある雑貨のID
      required: true
      schema:
        type: integer
        format: int64
  requestBody:
    content:
      application/x-www-form-urlencoded:
        schema:
          properties:
            name:
              type: string
              description: 雑貨の名前を更新
            status:
              type: string
              description: 雑貨のステータスを更新
  responses:
    '405':
      description: 無効な入力
      content: {}
  security:
    - goodsstore_auth:
        - 'write:goods'
        - 'read:goods'
delete:
  tags:
    - goods
  summary: 雑貨を削除します。
  operationId: deletePet
  parameters:
    - name: api_key
      in: header
      schema:
        type: string
    - name: goodsId
      in: path
      description: 削除する雑貨ID
      required: true
      schema:
        type: integer
        format: int64
  responses:
    '400':
      description: 無効なIDが指定されました
      content: {}
    '404':
      description: 雑貨が見つかりません
      content: {}
  security:
    - goodsstore_auth:
        - 'write:goods'
        - 'read:goods'

paths:

'/goods/{goodsId}':

get:

tags:

- goods

summary: IDで雑貨を見つける

description: 単一の雑貨を返します。

operationId: getGoodsById

parameters:

- name: goodsId

in: path

description: 返す雑貨のID

required: true

schema:

type: integer

format: int64

responses:

'200':

description: 成功

content:

application/json:

schema:

$ref: '#/components/schemas/Goods'

application/xml:

schema:

$ref: '#/components/schemas/Goods'

'400':

description: 無効なIDが指定されました

content: {}

'404':

description: 雑貨が見つかりません

content: {}

security:

- api_key: []

post:

tags:

- goods

summary: フォームデータでストア内の雑貨を更新します。

operationId: updateGoodsWithForm

parameters:

- name: goodsId

in: path

description: 更新する必要がある雑貨のID

required: true

schema:

type: integer

format: int64

requestBody:

content:

application/x-www-form-urlencoded:

schema:

properties:

name:

type: string

description: 雑貨の名前を更新

status:

type: string

description: 雑貨のステータスを更新

responses:

'405':

description: 無効な入力

content: {}

security:

- goodsstore_auth:

- 'write:goods'

- 'read:goods'

delete:

tags:

- goods

summary: 雑貨を削除します。

operationId: deletePet

parameters:

- name: api_key

in: header

schema:

type: string

- name: goodsId

in: path

description: 削除する雑貨ID

required: true

schema:

type: integer

format: int64

responses:

'400':

description: 無効なIDが指定されました

content: {}

'404':

description: 雑貨が見つかりません

content: {}

security:

- goodsstore_auth:

- 'write:goods'

- 'read:goods'

エディタで使用

エディタのエクステンションとして使用することができます。

VS Code

VS Code には「OpenAPI (Swagger) Editor」や「Swagger Viewer
」エクステンションがあります。

インストール

EXTENSIONS: MARKETPLACE で「swagger」または「openapi」と入力すると、エクステンションが表示されるので選択してインストールを行います。
OpenApiのjsonを選択すると左に「OpenAPI」アイコンを表示されるので選択すると使えるようになります。「Swagger Viewer」と一緒に使うとWeb版と同様な編集とプレビューが同時にできます。

備考

SwaggerHubは、OpenAPI 仕様をクラウド上で設計、ドキュメント生成できる統合環境で、とても便利です。クラウドでの作業に問題なければこちらのほうがより洗礼されているようですので、おすすめです。
また、Swagger Codegen からフォークした OpenAPI Generator もあるようです。

Swagger Tools で OpenAPI に準拠した API 設計

OpenAPI/Swagger

OpenAPI仕様

Swagger Tools

Swagger UI

インストール

Swagger Editor

インストール

使い方

File

Edit

Insert

Swagger Codegen

YAML ファイル

エディタで使用

VS Code

インストール

備考

関連リンク

返信を残すコメントをキャンセル

OpenAPI/Swagger

OpenAPI仕様

Swagger Tools

Swagger UI

インストール

Swagger Editor

インストール

使い方

File

Edit

Insert

Swagger Codegen

YAML ファイル

エディタで使用

VS Code

インストール

備考

関連リンク

返信を残す コメントをキャンセル

返信を残すコメントをキャンセル