Swagger 3.0 入門

【第1回】Swagger(OAS) 3.0の登場

APIエコノミー・マイクロサービス時代が到来し、APIやサービスの組み合わせによるシステム構築が当たり前になってきています。

そんな中、API仕様記述フレームワークであるSwaggerの勢いはとどまることを知らず、非常に多くの方が使われていると感じます。

2017年7月26日にSwagger 3.0(OAS:Open API Specification 3.0)が公開されました。Swagger Specと呼ばれるAPI仕様をよりシンプルに記述できるようになり、再利用性(componentsによる再利用部分の集約)が向上しています。

今回以降は、Swaggerは知っているけれども、2.0か3.0か迷っている。最新のSwagger動向が知りたい方向けに解説していきます。そもそもSwaggerって何？という方はこちらをご覧ください。

OAIにおけるSwaggerの位置付け

さきほど、「Swagger 3.0(OAS:Open API Specification 3.0)」と書きましたが、実は今回の3.0へのバージョンアップより、Swaggerは位置付けが変わっています。まずはその点を説明しておきましょう。

Smarter Bear社のSwaggerは2015年12月31日に、マイクロソフトやグーグルなどにより設立されたOAI(Open API Initiative)に寄贈され、Swagger SpecはOASへと名称変更されました。Swagger Specの1行目に記載する識別子が、swaggerからopenapiになり、バージョンも2.xから3.xになりました。

Smarter Bear社のSwaggerツールはSwagger 3.0へのバージョンアップ変更に追従するなど相変わらず動きが活発です。OAI公式サイトに掲載されているツールは以下です。

　

Swagger 3.0の記述方法

では、Swagger 3.0の記述方法を、より具体的に見てみましょう。

先ほども掲載しましたが、Swagger 3.0の変更点をまとめると以下のようになります。

Swagger 3.0では、例えば、以下のように記述します。

openapi: 3.0.0
info:
  version: 1.0.0
  title: Simple API
  description: Simple API

servers:
  - url: https://example.io/v1

security:
  - BasicAuth: []

paths:
  /users:
    get:
      description: Returns a list of users 
      parameters:
       - $ref: '#/components/parameters/PageLimit'

# 中略

  /items:
    get:
      description: Returns a list of items 
      parameters:
       - $ref: '#/components/parameters/PageLimit'

# 中略

components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic

  parameters:
    PageLimit:
      name: limit
      in: query
      description: Limits the number
      schema:
        type: integer

1行目に[openapi]項目によりSwagger Specのバージョンを定義します。

以降、[info][servers][security]といった形でURLや認証方法などを記述します。

前述の再利用性に関しては、[/users]パスと[/items]パスの表示数の上限パラメータ[Pagelimit]のように[$ref]参照し、複数回繰り返し登場する項目をcomponents属性により1箇所で集約管理します(記述例の赤字参照)。 

なお、Swagger 3.0の詳細については、OAIのgithubサイトをご覧ください。

[Field Name][Type][Description]のセットで構成されており、例えば[paths]を[Paths Object]-[Path Item Object]と辿っていくと、HTTPメソッドの定義[get][put][post]などを確認できます。

Swaggerツール群の全体像

Swaggerの公式サイトにアクセスすると、以下の通り[Design]、[Build]、[Document]、[Test]、[Standardize]の5つに大別されています。

各領域がどうなっているかを確認して見ましょう。

例えば[Design]クリックすると、[Swagger Editor]と[SwaggerHub]の2つのツールが表示されます。

同様に他の領域も見ていくと、5つの領域に対して以下の表のようにSwaggerツールが対応しています。

Swaggerは基本的には無償ですが、SwaggerHubについては無償版の[Free]に加えて、有償版の[Team]、[Enterprise]も提供されています。

Swagger 3.0への対応状況

Swaggerツール群のGitHubをみると、各ツールの概要が掴めるだけでなく、各ツールの最新更新日や直近1年間のアクティビティの活発さを確認することができます。

[swagger-codegen]をクリックして内容を確認してみましょう。

[Compatibility]をみると、現時点ではSwagger 3.0へ未対応であることがわかります。

なお、Swagger Core/UI/Editorについては、Swagger 3.0へ対応済みです。読者の皆様のプロジェクトにおいて、Swagger 2.0/3.0のどちらのバージョンを使うにしても、対応するバージョンを事前に確認しておくことをお勧めします。

Swagger 3.0への移行

すでにSwagger 2.0を利用されている方向けに、コンバータを用いたバージョン移行が可能です。

以下のサイトの[Paste Swagger 2.0 here]欄にSwagger 2.0で書かれたテキストを入力し、[Convert Swagger/OpenAPI 2.0]をクリックすることで、Swagger 3.0に変換されたテキストが返されます。

例えば、以下のようなSwagger 2.0で記載されたAPI仕様を入力すると、Swagger 3.0のAPI仕様が返されます。

swagger: '2.0'
info:
  version: 0.0.0
  title: Simple API
paths:
  /:
    get:
      responses:
        '200':
          description: OK

openapi: 3.0.0
servers: []
info:
  version: 0.0.0
  title: Simple API
paths:
  /:
    get:
      responses:
        '200':
          description: OK

まとめ

Swagger 3.0が登場し、記載がシンプルになり再利用性も向上しました。さらには、SwaggerがOAIに寄贈された後もSwaggerツール群は進化を続けており、SwaggerHubやSwagger Inspectorといったツールも出てきています。

Swagger Codegenなど、Swagger Spec 3.0に未対応のツールもあるので、Swagger Spec 2.0/3.0のどちらのバージョンを使うかについては、利用するツールに応じて検討すると良いでしょう。