初めてSwagger(OpenAPI)を使ってみたので、それの感想を書くだけのお話

皆様初めまして。システム事業部の吉成です。

このブログに初めて投稿させていただきます。

今回はタイトルにもある通り、

業務で初めて使うことになったSwagger(OpenAPI)を使ってみた感想を書いていこうと思います。

Swagger(OpenAPI)について

Swagger(OpenAPI)とはどういうものか、ほんの少しだけ軽く説明しようと思います。

f:id:zenet-tech:20210317095829p:plain

Swagger(OpenAPI)とは？

Swaggerとは、RESTful APIを定義するためのオープンソースのフレームワークです。

Swagger SpecやSwagger Editer等のツールが提供されています。

Swagger Specは、バージョン3.0でOpenAPI Specificationへと名前が変わりました。

現在のOpenAPI Specificationの最新バージョンは3.0.3となっています。

OpenAPI Specification公式サイト: https://swagger.io/specification/ Swagger Editer : https://editor.swagger.io/

基本的な書き方

基本的には、下記のように書いていけばSwagger(OpenAPI)が作成できます。

（下記の例はYAML形式でかいていますが、JSON形式で書くこともできます。）

下記で使用したもの以外にも指定できるオプション等がありますが、ここでは割愛させていただきます。

openapi: 3.0.3  #OpenAPIのバージョン。基本的に最新バージョンを書けばOK

info:  #APIのメタデータ。
  title: Company and User API  #APIのタイトル。
  description: CompanyとUserのデータを取得するAPI群。  #APIについての説明。
  version: 1.0.0  #このAPIのバージョン。新規で作成するなら基本的に1.0.0と書けばOK。

servers:  #APIを提供するサーバー。複数定義可能。
  - url: https://sample-api.com/v1  #APIサーバーのURL。
    description: APIのサーバー。  #APIサーバーについての説明。

paths:  #APIのエンドポイントやメソッドを定義する。
  /companies:  #エンドポイントのパス。
    get:  #HTTPメソッド。
      tags:  #メソッドに付けるタグ。
        - companies
      summary: Company取得  #メソッドの概要
      description: Companyのデータを全件取得する。  #メソッドについての説明。
      responses:  #レスポンスの定義。
        '200':  #HTTPステータス。
          description: CompanyのデータをJSON形式で返す。  #レスポンスについての説明。
          content:
            application/json:  #レスポンスの形式。
              schema: 
                type: array  #レスポンスの型。
                items:
                  $ref: '#/components/schemas/Company'  #componentsで定義したモデルを参照する。
  /users: 
    get:
      tags:
        - users
      summary: User取得
      description: Userのデータを全件取得する。
      responses:
        '200':
          description: UserのデータをJSON形式で返す。
          content:
            application/json:
              schema: 
                type: array
                items:
                  $ref: '#/components/schemas/User'

components:  #APIで使用するオブジェクトを定義する。
  schemas:  #モデルを定義。
    Company:  #モデル名。
      type: object  #モデルの型。
      required:  #必須項目を定義。
        - id
      properties:  #モデル内のカラムを定義
        id:  #カラム名
          type: integer  #カラムの型。
        name:
          type: string
    User:
      type: object
      required:
        - id
        - company_id
      properties:
        id:
          type: integer
        company_id:
          type: integer
        name:
          type: string