📌

OpenAPIとSwagger 入門

2021/07/22に公開

Swagger

OpenAPI

tech

OpenAPIとSwaggerの違い

What Is the Difference Between Swagger and OpenAPI?

OpenAPI: RESTful APIの仕様を記述するためのフォーマット
Swagger: OpenAPIを使用するツールのこと

Swaggerのツールは、色々ありますが以下の3つがよく使われるようです。

名前	概要
Swagger Editor	ブラウザ上でAPI仕様書を書くためのエディタ
Swagger UI	API仕様書からドキュメントを生成するツール
Swagger Codegen	API仕様書からコードを生成するツール

それぞれの起動手順を見ていきます。

起動手順

Swagger Editor

Swagger Editorはオンライン版があるので、それを使います。

ローカルからSwagger Editorを起動する場合は、次のコマンドをターミナルから実行します。yarnは事前にグローバルインストールしています。

% git clone https://github.com/swagger-api/swagger-editor.git
% cd swagger-editor
% yarn dev

ブラウザからhttp://localhost:3200/ にアクセスします。

Swagger UI

GitHubにあるswagger-api/swagger-uiを参考にします。

% git clone https://github.com/swagger-api/swagger-ui.git
% cd swagger-ui
% yarn dev

ブラウザからhttp://localhost:3200/ にアクセスします。既に3200のポートを使用している場合は、ポート番号を適当なものに変更してください。

読み込んでいるJSONファイルを変更したい場合は、dev-helpers/index.htmlのurl: "https://petstore.swagger.io/v2/swagger.json",の指定を変えてあげると良さそうです。

Swagger Codegen

https://petstore.swagger.io/v2/swagger.json をもとにコードを生成し、Node.jsのモックサーバーを作成します。

% brew install swagger-codegen
% brew install wget
% wget -P　~/Documents　https://petstore.swagger.io/v2/swagger.json --no-check-certificat
% mkdir swagger-codegen-sample
% swagger-codegen generate -i ~/Documents/swagger.json -l nodejs-server -o swagger-codegen-sample
% yarn start

ブラウザからhttp://localhost:8080/ にアクセスします。

ターミナルからAPIを叩いてみます。

% curl -X GET "http://localhost:8888/v2/user/1"

以下のように返ってくれば成功です。

{
  "firstName": "firstName",
  "lastName": "lastName",
  "password": "password",
  "userStatus": 6,
  "phone": "phone",
  "id": 0,
  "email": "email",
  "username": "username"
}

Stoplight Studio

Swagger EditorでYAMLを書かなくてもStoplight StudioというAPI仕様を記載するためのエディタを使うことで、GUIで直感的にAPI仕様を記述することが出来るようです。

Macのアプリケーションがあるので、それをダウンロードしてAPIの作成を行います。

以上です。