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

Transcript

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

   View Slide

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

   View Slide

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

   View Slide

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

   View Slide

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

   View Slide

6. OpenAPI
   

   View Slide

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

   View Slide

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

   View Slide

9. OpenAPI（OAS）の記述
   

   View Slide

10. 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
    

    View Slide

11. 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
    

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

15. モックサーバ作成
    

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide