Swagger(OAS) 3.0の登場

【連載】

Swagger 3.0 入門

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

[2018/07/17 07:30]正野 勇嗣 ブックマーク ブックマーク

  • 開発ソフトウェア

開発ソフトウェア

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

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

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

Swagger 3.0での変更点

今回以降は、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になりました。

バージョンと識別子(Swagger Specの1行目)の対照表

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

OAI公式サイトに掲載のSwaggerツール(赤字)

 

Swagger 3.0の記述方法

では、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 Spec 3.0の定義

Swaggerツール群の全体像

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

Swaggerの公式サイトのトップページ

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

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

API Design領域に対応するツール群

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

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

5つの領域に対応するSwaggerツール

Swaggerツール群の関係性

Swagger 3.0への対応状況

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

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

Swaggerツール群の開発状況

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

Swagger Codegenの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に変換されたテキストが返されます。

OpenAPI 3.0.0 converter

例えば、以下のような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のどちらのバージョンを使うかについては、利用するツールに応じて検討すると良いでしょう。 

著者紹介


正野 勇嗣 (SHONO Yuji ) - NTTデータ 課長

2011年まで開発自動化技術のR&Dに従事。その後、開発プロジェクト支援やトラブルシューティング等に主戦場を移す。「ソースコード自動生成」に加えて、JenkinsやMaven等の「ビルド自動化」、JsTestDriverやSelenium等の「テスト自動化」を扱うようになり、多様化する開発自動化技術動向に興味。

最近は第四の自動化であるInfrastructure as Code等の「基盤自動化」の魅力に惹かれている。開発自動化技術に関する雑誌・記事執筆も行う。2児のパパ。

※ 本記事は掲載時点の情報であり、最新のものとは異なる場合がございます。予めご了承ください。

関連リンク

この記事に興味を持ったら"いいね!"を Click
Facebook で IT Search+ の人気記事をお届けします
3854
2
【連載】Swagger 3.0 入門 [1] Swagger(OAS) 3.0の登場
APIエコノミー・マイクロサービス時代が到来し、APIやサービスの組み合わせによるシステム構築が当たり前になってきています。そんな中、API仕様記述フレームワークであるSwaggerの勢いはとどまることを知らず、非常に多くの方が使われていると感じます。本連載では、昨年7月にリリースされた3.0をベースに、Swaggerの仕様や使い方を改めて解説いたします。
https://news.mynavi.jp/itsearch/2018/07/13/swagger3/Swagger3-300-250.jpg
APIエコノミー・マイクロサービス時代が到来し、APIやサービスの組み合わせによるシステム構築が当たり前になってきています。そんな中、API仕様記述フレームワークであるSwaggerの勢いはとどまることを知らず、非常に多くの方が使われていると感じます。本連載では、昨年7月にリリースされた3.0をベースに、Swaggerの仕様や使い方を改めて解説いたします。

会員登録(無料)

注目の特集/連載
AI人材に必要なもの
はじめてのRPA導入
教えてカナコさん! これならわかるAI入門
RPA入門
PowerShell Core入門
パスワード管理アプリの選び方
徹底研究! ハイブリッドクラウド
マイナビニュース スペシャルセミナー 講演レポート/当日講演資料 まとめ

一覧はこちら

今注目のIT用語の意味を事典でチェック!

一覧はこちら

ページの先頭に戻る