WebAPI
swagger

swagger introduction

More than 1 year has passed since last update.

tl;dr

  • swaggerを使うとWebAPIの仕様書を決められたフォーマットに沿って作成できる
  • API更新に追従して仕様書の自動更新ができる
  • 将来的にはWebAPI仕様書の標準フォーマットになるかも?

メモ

  • swagger coreとcodegenの役割が少し曖昧になっているから、明確化したい。

swaggerとは

  • swaggerはREST APIのドキュメント記載に関するフォーマット仕様
  • RESTful API標準化団体(Open API Initiative)が採用。OpenAPI Specificationとして定義されている。
  • 実態はJSON(YAML)形式のAPI仕様書とそれを取り巻くツール群
  • swaggerプロジェクト自体はフォーマット仕様以外にもドキュメントを書きやすくするツール、ドキュメント自動生成、ウェブベースのドキュメントビューワ等を提供している。

swaggerでのAPI仕様書生成方式

  • トップダウン
    • 仕様を定義(swagger editor)で定義ファイルを生成し、公開(swagger ui)
    • 定義ファイルからソースコードを生成(swagger codegen)
  • ボトムアップ
    • 既に存在するREST APIのソースコードから定義を作成する(swagger core)
    • コード内にはSwagger用のAnnotationが書いてあること前提(JavaDocのようなものか)
    • 生成された定義を公開(swagger ui)

swaggerの構成要素

image

  • Swagger Specification
    • フォーマット仕様
    • 仕様に沿ってJSON(YAML)形式でAPI定義を記述する。以下サンプル
swagger: '2.0'

info:
  version: "1.0.0"
  title: 日本語のテスト

paths:
  /auth:
    get:
      description: |
        test description
        日本語説明文

      parameters:
        -
          name: size
          in: query
          description: Size of array
          required: true
          type: number
          format: double

      responses:
        200:
          description: Successful responses
          schema:
            title: ArrayOfPersons
            type: array
            items:
              title: Person
              type: object
  • Swagger Editor

    • Swagger Specificationに沿って記述されたJSON(YAML)ファイルを編集するWebベースのツール。swaggerの公式ページで動作しているものを使うか、ツールをダウンロードしてローカルで動作させる。
    • ツールはNode.js製なのでローカルで使う場合は要Node.js image
  • Swagger UI

    • Swagger Specificationに沿って記述されたJSON(YAML)ファイルのビュワー。Webベースのインタフェース。公式ページでデモが公開されている。 image
  • Swagger Codegen

    • swaggerの定義ファイル(json)から実際のプログラムコード(サーバ側・クライアント側)を生成するツール。
    • 出力言語は様々(ruby, python, node, php)対応している。
  • Swagger Core

    • 実際のプログラムコードからswagger定義(json)を生成する。

その他のAPI仕様

参考文献