OpenAPIとは？
OpenAPIに触れたので調べてみました。
OpenAPIとは？
OpenAPIと呼ばれているのは、
厳密にはOpen API Specification (OAS)のこと。
OASとは、RESTfulAPIを定義するフォーマットのこと。
OpenAPI Specification (formerly Swagger Specification) is an API description format for REST APIs.
APIを定義って具体的にどういうこと？
APIのHTTPメソッドやパス、パラメータや、レスポンスの型などの情報を、フォーマットに則って定義したりできます。
英語ですが、こんな感じで書いてありました。
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を定義して何ができる？何が嬉しい？
OpenAPIの関連ツールを使うことで、
API定義をもとにコード生成したり、ドキュメント生成したりできるので、開発が楽になったり、メンテが楽になったりします。
スキーマファーストや、スキーマ駆動開発というワードで調べると、
いろいろメリットや恩恵などが出てきます。
スキーマファーストに注目があつまった経緯
HTTP APIにおけるRESTやSOAP、JSON, XMLなどシステム間のRPCにおけるレスポンスフォーマットやリクエストフォーマットは、様々ものが存在し標準化が難航していました。
RRRREST/JSONの事実上の標準化に伴いリクエスト/レスポンスbodyのフォーマットが定まったことから近年標準化が一段階推し進みドキュメント記述方法の標準化（OpenAPI）やランタイムやクエリも含めたプロトコル（GraphQL, gRPC）が開発されスキーマからサーバコード、クライアントコード、ドキュメントまで自動生成が可能になる土壌が生まれ、スキーマファーストでの開発に注目が集まりました。
OpenAPIどうやって使うの？
使うツールなどによって、いろいろなことができるので、
一旦、OASの書き方について、以下の記事だけ紹介します。
Open APIの関連ツール
Open APIに関連するツールには、以下のようなものがあるみたいです。
いろいろ調べたところ下記のような周辺ツールも含めてOpenAPIと呼ばれているようです👀
Swagger Editor:
OpenAPIを使ったAPI定義を良い感じにプレビューしながら書けるエディター
Swagger UI:
OpenAPIを使ったAPI定義(yaml or json)からWebで閲覧可能な良い感じのAPI定義書を生成する
OpenAPI Generator:
OpenAPIを使ったAPI定義(yaml or json)からStabを作成するツール
また、以下のような便利ライブラリがあります。
committee-rails
committeeは、OpenAPIで定義したスキーマを利用してリクエストとレスポンスの検証を行うミドルウェアを提供してくれます。
rspec-openapi
RSpec の request spec から OpenAPI 仕様のドキュメントを出力する Gem
この記事が気に入ったらサポートをしてみませんか？