OpenAPIについて（第1回）
担当しているプロダクトではAPIの仕様を定めるのに少し前からOpenAPIを使い始めました（まだごく一部ですが）。
なので改めてOpenAPIについてまとめてみようと思います。数回に分けて書く予定です。
OpenAPIとは
OpenAPI Specification (formerly Swagger Specification) is an API description format for REST APIs. An OpenAPI file allows you to describe your entire API, including:
- Available endpoints (/users) and operations on each endpoint (GET /users, POST /users)
- Operation parameters Input and output for each operation
- Authentication methods
- Contact information, license, terms of use and other information.
API specifications can be written in YAML or JSON. The format is easy to learn and readable to both humans and machines. The complete OpenAPI Specification can be found on GitHub: OpenAPI 3.0 Specification
上記の通り、OpenAPIとはREST APIを記述するフォーマットのことであり、エンドポイントやリクエストパラメータ、レスポンス、認証方法等の情報も含めることができます。
このフォーマットに沿って書くことで人間も機械も読めるAPI仕様書になる、というわけです。
Swaggerとは
OpenAPIについて調べてみるとSwaggerという単語がほぼセットで出てきます。
このSwaggerとはOpenAPIを使ってREST APIを設計する際に使用するオープンソースのツールをまとめた総称です。
主なものとしては以下のようなものがあります。
Swagger Editor
ブラウザ上で動作するOpenAPIエディタです。
↑のリンクを開くとサンプルが書かれています。
ページ上部のメニューのGenerate Clientから言語を選択するとzipファイルがダウンロードされ、解凍して中身を見ると、
こんな感じで記述した内容に沿ってコードが自動で生成されています。便利。
Swagger UI
OpenAPIの内容を見やすいUIでレンダリングしてくれるツールです。
Swagger Editorの右半分に出ているのがそれです。
ちなみにGitlabでは内部でSwagger UIが組み込まれているのでOpenAPI形式のファイルをコミットすると綺麗にレンダリングしてくれます。
Interactive API documentation | GitLab
Swagger Codegen
OpenAPI形式で記述されたファイルからコードを自動で生成してくれるツールです。
Swagger EditorのGenerate ClientやGenerate Serverも（多分）このツールを使用しています。
Swagger以外にもコード生成ツールで言うとOpenAPI Generatorがあったり、OpenAPIから静的HTMLファイルに書き出してくれるRedoc等、様々なツールがあるので調べてみると面白いです。
まとめ
今回は導入編ということでOpenAPIとSwaggerについて書きました。
次回は実際に書いてみるところに入っていきたいと思います。
