Lock in $30 Savings on PRO—Offer Ends Soon! ⏳

WebAPI開発のためのOpenAPI入門/entry-open-api

marchin
June 15, 2023

 WebAPI開発のためのOpenAPI入門/entry-open-api

marchin

June 15, 2023
Tweet

More Decks by marchin

Other Decks in Programming

Transcript

  1. 前置き 対象者 - 業務でAPI仕様書を利用する、作成する方 - OpenAPIを知らない方、触ったことがない方 - OpenAPIでできることを知りたい方 前提とする知識 -

    HTTPの基礎知識がある程度あること - API仕様書を利用したことがあること 注意 - 最近流行りの「OpenAI API」ではなく、「OpenAPI」についての話をします。全く別物なので 注意。
  2. OpenAPI - OpenAPI Specificationは、WebAPI(REST)のインターフェースを記述するための 仕様。フォーマット。 - OpenAPI Specificationを、OASといったり、OpenAPI Specといったりする。 -

    JSONとYAMLで記述が可能。 - 現在(2023/06/16)の最新バージョンはv3.1.0。 - OASに対応している各種周辺ツール、 サービスの対応状況によっては、 まだv3.0.3、もしくは2系を使う選択肢もある。
  3. OASの構造 トップレベルに定義できるオブジェクト(OpenAPI Object)をいくつか紹介。 - openapi - 自身のファイル、OASのバージョン。3.1.0や3.0.3など指定。 - info -

    このAPIの情報(タイトル、バージョン、作者など)を記述。 - titleとversionが必須。 - paths - APIのエンドポイントを記述。 - メソッドやリクエストパラメータ、レスポンスなどを記述。 出典: OpenAPI - Minimal Document Structure https://learn.openapis.org/specification/structure.html#minimal-document-structure
  4. OASの構造 その他のオブジェクトを紹介。 - components(Components Object) - OASの再利用可能なオブジェクトを記述。 - APIのリクエストやレスポンスなどで参照できる。 -

    servers(Server Object) - APIのベースURLを記述。 - URL内に変数を含めることができる。ドメインやポート、バージョンなどを変数で表現可能。 出典: OpenAPI - Reusing Descriptions https://learn.openapis.org/specification/components.html 出典: OpenAPI - API Servers https://learn.openapis.org/specification/servers.html
  5. 参考文献 ・OpenAPI INITIATIVE. https://www.openapis.org/ ・OpenAPI Generator. https://openapi-generator.tech/ ・Software Design 2022年8月号,

    技術評論社, 2022 ・Swagger. https://swagger.io/ ・Stoplight. Prism. https://stoplight.io/open-source/prism