Zenn
🍏

OpenAPIについて学ぶ

2023/02/25に公開
API
OpenAPI
tech

はじめに

  • 今まで存在は知っていたものの、実務で使うことがなくてどんなものか理解していなかったOpenAPI。今年からジョインしたチームではOpenAPIを導入して開発していることもあり、早くOpenAPIについて理解しないといけない！と思い、OpenAPIについて調べたこと・やってみたことをまとめていきます。

API開発における課題

  • バックエンドエンジニアとして色々な現場でAPIの開発をしてきましたが、その際にAPI仕様書を必ず作ってきました。
    • エクセル（スプレッドシート）
    • dockbaseやNotion等の各種ドキュメント管理ツール
  • どの現場でもAPI仕様書を管理するのですが、開発を進めるにつれて「実装とAPI仕様に大きな乖離が生まれてくる」ようになり・・・。結局、ドキュメントのメンテナンスがめんどくさくなり、「ソースコードが仕様」となってしまうプロジェクトが多くありました。（API仕様書とコードの実態が合ってない）
  • ドキュメントとして作成しなければいけないので気軽にAPI仕様書を起こすことができず、フォーマットやらも考えながら作らないといけないのでAPI仕様の作成コストが高いと感じることが多くありました。あとは仕様書が増えてくると管理も大変に・・・
  • "もう少し楽にAPI仕様書を管理できたら幸せなのになぁ"・・・と思ったことは一度や二度ではありません。

OpenAPIってなんだ？

  • 上記であげたような課題を解決すべく、なにやら「OpenAPI」というものがあるそうです。

引用：https://nonamesecurity.com/learn-what-is-openapi

  • What is OpenAPI?

Originally known as the Swagger Specification, the OpenAPI Specification (OAS) is a format that can be used to describe, produce, consume, and visualize RESTful web services. It's a specification standard for REST APIs that defines the structure and syntax.

引用：https://swagger.io/docs/specification/about/

  • What is 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:

  • OpenAPIとは

    • OpenAPI Specification(OAS): REST APIの記述フォーマット(または記述)のこと
    • インターフェースの定義は JSON または YAML で記述
    • 特定の言語に依存しない, さまざまな言語による実装を利用できる

  • なにやら「Swagger」というものもOpenAPIにおいてキーワードになっていそう

引用：https://www.seplus.jp/dokushuzemi/blog/2020/04/tech_words_openapi.html

以前は Swagger という名称だったが、Swagger が（現在 OpenAPI を策定している）OpenAPI Initiative へ寄贈された際に名称変更が行われた。

  • なるほど、JSON および YAML で定義ファイルを作成することで、簡単にAPI仕様が作れるらしい！！すごい・・・早速やってみよう。

実践: OpenAPIを使ってみる

  • 何はともあれ、まずはOpenAPIを使ってAPI定義を作ってみます
  • 普段から使用しているIntelliJ IDEAを使っていきます

OpenAPI:YAMLのフォーマット

  • 6つのスキーマがある
openapi: 3.0.3 # 使用するOpenAPIのバージョン
info: # API定義の基本情報
  title: SampleAPI
  description: SampleAPIの定義
  version: 1.0.0
servers: # APIサーバーの情報/複数の開発環境を記入できる
  - url: 'http://kuroiwa-dev.com'
    description: 開発環境
  - url: 'https://kuroiwa-prod.com'
    description: 本番環境
paths: # paths以下にAPI定義を記述していく
tags: # APIを整理するためのタグ情報を記述
components: # 個別のスキーマ情報を記述

ユーザー情報取得/商品情報取得 APIの定義を作る

  • シンプルなGETのAPI定義を作ってみた
openapi: 3.0.3 # 使用するOpenAPIのバージョン
info: # API定義の基本情報
  title: Sample OpenAPI
  description: SampleAPIの定義
  version: 1.0.0
servers: # APIサーバーの情報/複数の開発環境を記入できる
  - url: 'http://kuroiwa-dev.com'
    description: 開発環境
  - url: 'https://kuroiwa-prod.com'
    description: 本番環境
tags: # APIを整理するためのタグ情報を記述
  - name: 'users'
    description: ユーザー情報
  - name: 'products'
    description: 商品情報
paths: # paths以下にAPI定義を記述していく
  '/api/v1/users/':
    get:
      description: ユーザー情報取得(全件)
      tags:
        - users
      parameters: []
      responses:
        '200':
          description: A JSON array of User model
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User' # componentsに定義したスキーマ情報をロード
                example:
                  - id: 1
                    user_name: 黒岩テスト1
                  - id: 2
                    user_name: 黒岩テスト2
  '/api/v1/products/':
    get:
      description: 商品情報取得(全件)
      tags:
        - products
      parameters: []
      responses:
        '200':
          description: A JSON array of Product model
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Product' # componentsに定義したスキーマ情報をロード
                example:
                  - id: 1
                    product_name: 黒岩テスト商品1
                  - id: 2
                    product_name: 黒岩テスト商品2
components: # 個別のスキーマ情報を記述
  schemas:
    User:
      type: object
      required:
        - id
      properties:
        id:
          type: integer
        user_name:
          type: string
    Product:
      type: object
      required:
        - id
      properties:
        id:
          type: integer
        product_name:
          type: string

OpenAPI_1

OpenAPI_2

OpenAPI_3

最後に

  • YAMLでAPI定義が出来るということで、とても便利だなと思いました。
  • この記事ではGETのシンプルなAPIのみやってみましたが、今度はもう少し複雑なAPIの定義を書いてみようと思います。
  • OpenAPI凄く便利でした！！！

https://github.com/kuro-channel/openapi_sample

Discussion