『REST入門』OpenAPI (Swagger)の概要

OpenAPI(Swagger) Swagger

今まで外部に提出するためのドキュメントをWordで作成していたのですが、Swaggerで提供することになったので、勉強を兼ねて入門用としてSwaggerの概要についてまとめてみました。 「OpenAPIとは何ですか?」について公式サイトでも記述がありますので以下も参考にして下さい。 [公式サイト] Swagger.io - OpenAPIとは何ですか?

 

Swaggerとは

Swaggerとは、OAI (Open API Initiative) が採用しているRESTful APIを構築するためのオープンソースのフレームワークのことです。 Swaggerが提供するツール群には、OpenAPIの仕様に沿ったYAML(JSON)ファイルを作成するツール、YAML(JSON)ファイルから人間が見やすいドキュメントを作成、YAML(JSON)ファイルで書かれた仕様の通りに動作するスタブを生成するツールがあります。

 

OpenAPIとは

もとはSwaggerであり、2015年12月31日に設立されたOAIに寄贈され、OpenAPIに名前が変わりました。 また、Swaggerの仕様である「Swagger Spec」は「OAS(OpenAPI Specification)」に変わりました。 現在(2020/05/30)の最新は「OpenAPI 3.0.2」になります。 OpenAPI 3.0から世界標準となったそうです。

 

OAI (Open API Initiative)とは

RESTful APIのインターフェースを記述するための標準フォーマットを推進するのために結成された団体で、Google、Microsoft、などが参加しています。
[公式サイト] OAI (Open API Initiative)

 

Swagger Specとは

RESTful APIのインターフェースを定義するための仕様のことです。 Swagger 2.0までが「Swagger Spec」となります。

 

OAS (OpenAPI Specification) とは

RESTful APIのインターフェースを定義するための標準仕様のことです。 OpenAPI 3.0から「OAS」となります。
OpenAPIとは」で記述した通り、SwaggerからOpenAPIに名前が変わった際に、Swagger SpecからOASに変わり、Swagger Spec 2.0をOAS2.0と呼ぶようになりました。

[公式サイト] OpenAPI (Swagger) Specification

[公式サイト] Swagger.io - OpenAPI Specification

 

Swaggerのツール群

OpenAPIを用いたREST APIを設計するたのSwaggerで提供する主なツールとして以下のようなものがあります。

 

OAS (OpenAPI Specification)

REST APIを定義する際のOpenAPI仕様。

https://swagger.io/specification/

 

Swagger Editor

OASに基づいたYAML(JSON)ファイルを編集するためのエディタ。

以下のURIからウェブ上で利用が可能で、左側がエディタになり、右側で更新した内容をその都度確認でき、エラーチェックをしながら可視化が行え、Swagger UIで生成されるドキュメントがどのようなものかを確認できます。

初めて起動するとサンプルが記載されるので、イメージを付けやすいかと思います。気になる部分を変更して変化を見るのも手ですね。

以下はWeb版のSwagger editorになります。

https://swagger.io/tools/swagger-editor/

ローカルの環境にインストールして使用する事もできます。

以下の記事でインストール方法を解説していますので参考にしてください。

『REST入門』Swagger Editorのインストール(Windows )
ここではSwagger EditorをWeb上で利用するのではなく、ローカルで利用また、サーバ上に構築してチームで利用したといった場合のインストール方法を解説していきます。

 

Swagger UI

OASに基づいたドキュメントをHTML形式で閲覧・生成するツールのこと。

以下はWeb版のSwagger UIになります。

https://swagger.io/tools/swagger-ui/

ローカルの環境にインストールして使用する事もできます。

以下の記事でインストール方法を解説していますので参考にしてください。

『REST入門』Swagger UIのインストールとIISでAPI仕様書を公開(Windows )
ローカル環境でSwagger UIを利用するためのインストール方法と、Swagger または OpenAPI Specification に沿って記述されたAPI仕様書をIISで公開するまでを解説していきます。 こちらはWindows10...

 

Swagger Codegen

OASに基づいたYAML(JSON)ファイルから API を自動で生成するツールのこと。

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

 

タイトルとURLをコピーしました