WebAPI開発のためのOpenAPI入門 ~OpenAPI Specificationを利用して開発効率をアップしよう~

自己紹介 名前　：阿部 真之 仕事　：株式会社ゆめみ。サーバーサイド、Androidのリードエンジニア 趣味　：コーヒー、ビール、アニメ、ゲーム、読書、etc… Twitter：@marchin_1989

前置き 対象者 - 業務でAPI仕様書を利用する、作成する方 - OpenAPIを知らない方、触ったことがない方 - OpenAPIでできることを知りたい方 前提とする知識 - HTTPの基礎知識がある程度あること - API仕様書を利用したことがあること 注意 - 最近流行りの「OpenAI API」ではなく、「OpenAPI」についての話をします。全く別物なので 注意。

- OpenAPIの概要 - OpenAPIの記述 - クライアントコード、サーバサイドコードの自動生成 - モックサーバ作成 - まとめ アジェンダ

API仕様書のよくある課題 - Excel仕様書が読みづらい、メンテしづらい - フォーマットが統一されていない - API仕様書と実装が一致していない - リクエストやレスポンスのクラス設計と実装が、ほぼAPI仕様書通りなので二度手 間感がある

OpenAPI

OpenAPI - OpenAPI Specificationは、WebAPI（REST）のインターフェースを記述するための 仕様。フォーマット。 - OpenAPI Specificationを、OASといったり、OpenAPI Specといったりする。 - JSONとYAMLで記述が可能。 - 現在（2023/06/16）の最新バージョンはv3.1.0。 - OASに対応している各種周辺ツール、 サービスの対応状況によっては、 まだv3.0.3、もしくは2系を使う選択肢もある。

OpenAPIのメリット - 書き方が仕様で決まっているおかげで、API仕様書のフォーマットを統一できる。 - OpenAPIの仕様に準拠したツール（プログラム）があり、クライアント、サーバの コードなど、自動生成することが可能。 - OpenAPIのエコシステムに乗っかることで、 さまざまな恩恵あり。

OpenAPI（OAS）の記述

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

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

OpenAPIを記述するためのツール - OASはただのテキストファイルなので、エディタがあれば記述は可能。 - ただし、プレビューなどを利用した方が効率がいいので、ツールを使うのがおすす め。 - 代表的なツール - Swagger Editor: ブラウザでOpenAPIのYAML（JSON）が記述できる。 - Stoplight studio: よりGUIベースでOpenAPIの記述が可能。 - IDEのplugin

実際に書いてみる（デモ）

クライアントコード、サーバサイドコードの自動生成

モックサーバ作成

OpenAPIのツールを探す方法（おまけ） - 公式がツールをまとめてくれているので参考にするとよい - https://tools.openapis.org/ - 各ツールのメンテ状況や、OASバージョン対応状況を見て判断するといい

まとめ - OpenAPI Specification（OAS）は、WebAPI（REST）のインターフェースを記述す るための仕様。フォーマット。 - API仕様書のフォーマットを統一できる。 - OASを用意すれば、クライアント、サーバのコードを自動生成可能。

参考文献 ・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

ご清聴ありがとうございました！