OpenAPI + Swagger でmocサーバを立てつつ、OpenAPIについて理解する
どもども、絶賛博多に移動中の僕です！新幹線で本記事を作成しております！
本日はOpenAPIとSwaggerでmocサーバを立てつつ、OpenAPIについて理解していきたいとおもいます。
お恥ずかしい話、僕自身つい先日までOpenAPIが如何なるものなのか存じ上げず、社内勉強会でその概要を知りました。
聞けば聞くほど便利だと思いましたので、これを気にキャッチアップしていきたいと思います！
OpenAPIとは
まず初めにOpenAPIとは一体何ができるものなのかを確認しておきましょう。Swaggerについては後ほどのセクションで確認します。
Swaggerの公式ページには以下のように紹介されています。
The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic.
https://swagger.io/specification/
要するにRESTful APIへの標準の言語に依存しないインターフェースを定義したものになります。言語に依存しないという点が非常に有用性を高めています。
APIの使用を理解できるように特定の形でそのロジックを適宜しておくことができます。そうすることで、例えばフロントエンドエンジニアは特にソースコードやドキュメントを読み解くことなく実装ができますし、企画などにコードを用いずにその仕様が意図した形になっているかを確認したりすることができます。
さらにSwaggerを利用することで、その定義をUIで確認できたり、設定通りのレスポンスを返却するmocサーバを立ち上げることができたりします。開発現場の各々が非同期にそれぞれの作業を進めることができるので開発速度が向上します。
これは使用しない手はないですね！早速使用してみましょう。
mocサーバを立ててみる
兎にも角にも検証環境がないことには学習は捗りません。早速 OpenAPI + Swagger で mocサーバを立ち上げてみましょう。
下記の記事にて手軽に構築できる方法が紹介されているので、こちらの方法を拝借させていただきましょう。
DockerでSwagger環境簡単構築！
丸ごと同じ手順で問題ございません。UIの立ち上げと、mocサーバからレスポンスが返ってくるところまで確認してください！
環境構築は完了しましたか？それでは、Swaggerの仕様やopenapi.yamlの中身をこれからみていきましょう。
Swaggerとは
Swaggerについて確認しましょう。公式ページには以下のように紹介されています。
Swagger allows you to describe the structure of your APIs so that machines can read them.
https://swagger.io/docs/specification/2-0/what-is-swagger/
Swagger は RESTful APIを記述してマシンが読み取れる構造体を構築するためのオープンソースのフレームワークです。OpenAPIとの関係性を完結に述べるなら、OpenAPIが記述したフォーマットを使用するのがSwaggerです。
もちろんSwagger以外にも同じ動作を実現できるものはありますが、今のところSwaggerが広く覇権を握っている状態であるといえるでしょう。
ここで一度docker-compose.yamlを見てください。Swagger関連のツールが複数存在することが確認できますね。
swagger-editor
swagger-ui
prismそれぞれどのようなことを可能にしてくれるのでしょうか。
– swagger-editor
ブラウザ上でAPIの使用を書いたりテストできたりします。実際に使用するにはdocker-compose upした状態でhttp://localhost:8001/に接続します。
接続すると左側にデフォルトで今回のopenapi.yamlの内容が記載され、右側で定義されたAPIを試すことができる状態になっているかと思います。
openapi.yamlの内容は後ほど確認していくとして、挙動の変化を確認するために左側の内容を少し書き換えてみましょう。
試しに左側の内容を全てdeleteしてみてください。当然右側の画面は"No API definition provided."になります。このように左を変更すれば右側もレスポンシブに変化してくれます。
5行目あたりにあるタイトルを"title: “Swagger Sample""に変更してみましょう。右側のタイトルも変化しましたね！
他にも定義の中身のtypeやpathなどを変更し、右側がどのように変わるか観察してみてください。swagger-editorの使用方法がなんとなくわかってくると思っています。
– swagger-ui
swaggger-uiはopenAPIによる定義をHTMLでレンダリングしてドキュメント化してくれます。
今回の環境だとhttp://localhost:8002/で接続することが可能です。swagger-editorの右側がそのまま見やすくなったイメージでしょうか。
実際にAPIの設計を企画や協力会社に共有するときに使用されるのはこのswagger-uiだと思います。swagger-editor同様内容がopenapi.yamlの内容に応じて自動で変化してくれるため大変便利です。
裏を返せば、APIを回収したものの、openapi.yamlの内容を更新しなかった場合、それぞれの差異は当然swagger-uiにも出てくるので常に並行更新を心がける必要があります。
– stoplight/prism
OpenAPI定義ファイルからからmocサーバを構築することが可能です。swagger-editorやswagger-uiで確認できるレスポンスの正体はこのprismになります。
openapi.yamlでレスポンスを定義しておいて、該当のAPIを叩くとそのレスポンスを返してくれるサーバを立ち上げることができます。
フロントエンドエンジニアがバックエンドエンジニアの実装を待つことなく開発を進めることができたりと、開発を非常に円滑に進めてくれるツールです。
このようにOpenAPIを使用した開発をより円滑にしてくれるのが、swaggerというわけです。
Yamlの内容を見てみる
最後に今回の記事の全ての源であるopenapi.yamlの中身をみてみましょう。すべて見ると時間がかなりかかるので一部分を取り上げてみます。
159行目をみてみましょう。下記のように定義されています。
get:
tags:
- "pet"
summary: "Find pet by ID"
description: "Returns a single pet"
operationId: "getPetById"
produces:
- "application/xml"
- "application/json"
parameters:
- name: "petId"
in: "path"
description: "ID of pet to return"
required: true
type: "integer"
format: "int64"
responses:
"200":
description: "successful operation"
schema:
$ref: "#/definitions/Pet"
"400":
description: "Invalid ID supplied"
"404":
description: "Pet not found"
security:
- api_key: []getメソッドが定義されていることがわかります。
summaryにはAPIの用途が、descriptionには具体的にどのような動作を行うのかを記載します。
producesには送受信するデータタイプを定義します。
parameterとresponseはREST APIではお馴染みですね！
このように全体的にシンプルに定義されていて読み解きやすいのがOpenAPIの良いところです。
もっと上位にserverやpathsなどの定義もありますが、APIが定義されているサーバ(今回の場合はPrism)やAPIを叩くためのpathを定義したりと上記以外の部分に関してもAPIを実装している方にとっては馴染みのある項目ばかりだと思います。
このyamlファイルを書くことができれば、自ずとswaggerも有効に利用できるようになると思います。
まとめ今回は
今回はOpenAPI + SwaggerでOpenAPIの基礎を理解してみる記事でした。
中・大規模Webアプリケーション開発において、APIが実装されるまで作業が進まないということはかなり厄介です。
企画、バックエンド、フロントエンドエンジニアなどによる非同期に高速な開発を実現するために、是非ともOpenAPIを使いこなしていきたいですね！
最後まで読んでいただきありがとうございました！