ゼロからOpenAPIを始めた話

はじめに

こんにちは、山田です。最近少しだけ涼しいと感じる反面、シャーベット系のアイスにハマり始めています笑。 入社してから3ヶ月が経過して、ようやく慣れてきました。 本記事は入社して2本目の記事で、今回は研修で学んだAPIドキュメント作成の話です。研修ではショッピングサイトのAPI作成に取り組んだのですが、想像以上にドキュメント作成に苦戦をしたので整理もかねて書いています。

OpenAPIとは

OpenAPIとは「OpenAPI Specification」の略でREST APIのコードやドキュメントを生成できるフォーマットのことを指します。API仕様書はExcelで作成すると様式の統一や管理のしにくさで問題が起こりやすいです。OpenAPIのフォーマットを用いることで、API仕様書の様式が統一されるため管理が楽になります。研修ではOpenAPI自体はツールではなく、APIの仕様書を作成するための一つの考え方ということを学びました。

SwaggerでAPIを設計する

SwaggerとはOpenAPIを実装するためのツールセットのことを指します。社内の研修ではツールの一つである「Swagger Editor」を用いてAPI設計を行いました。Swagger Editorはブラウザ上でOpenAPIを記述できるエディターです。左半分がエディターとなっており右半分は定義ファイルのAPI テストのための UI を提供しています。実際に左半分のエディターの内容を変更すると、そのまま右半分のUIも変化するため楽しみながら触ることができました。

editor.swagger.io

OpenAPIのフィールド

OpenAPIには以下のフィールドが存在しています。研修中に記述した内容を例に示しながら紹介していきます。

• openapi
• info
• externalDocs
• servers
• tags
• paths
• components

openapi

OpenAPI Specification (OAS)のバージョンを記述します

openapi: 3.0.3

info

API に関する情報を記述します。API の概要だったりライセンス形式だったり、 API そのものの情報をこちらに書くことができます。

info:
  title: Shopping API - OpenAPI 3.0
  description: |-
    This is a Shopping test.これは研修テストです。
  termsOfService: http://example.com/riyoukiyaku/hyoji/


  contact:
    email: [email protected]
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.0
externalDocs:
  description: Find out more about Swagger
  url: http://swagger.io

externalDocs

外部リンクを記述します。

externalDocs:
  description: Find out more about Swagger
  url: http://swagger.io

servers

実際に API が配備されているサーバーを記述します。

servers:
  - url: https://localhost/api

tags

APIを整理するために利用するタグを定義します。用途などに応じたグルーピングを行います。

tags:
  - name: 販売管理系
    description: 販売管理系API
    externalDocs:
      description: Find out more
      url: http://swagger.io
  - name: 受注系
    description: 受注系API
    externalDocs:
      description: Find out more about our store
      url: http://swagger.io
  - name: ユーザー管理系
    description: ユーザー管理系API
  - name: 商品管理系
    description: 商品管理系API

paths

URLのパス名の部分を表し、パス別にGET, POST, PUT, DELETEなどのREST APIの仕様を記述できます。リクエストパラメータやレスポンスに関してもここで記述します。（詳細なオブジェクトスキーマに関しては$refを用いて次項のcomponentsを呼び出すパターンが多いです。）APIの数だけ記述していかなくてはならないため、おそらく記述量が多くなりやすいフィールドかと思います。

paths:
  /products:
    get:
      tags:
        - 商品管理系
      summary: 商品情報の一覧を取得するAPI
      description: 商品情報の一覧を取得するAPI
      operationId: getproductlist
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Products'
    post:
      tags:
        - 商品管理系
      summary: 商品情報を新規追加するAPI
      description: 商品情報を新規追加するAPI
      operationId: postproductlist
      requestBody:
        description: 商品情報を新規追加するAPIリクエスト
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostProduct'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: integer

components

APIで使用するオブジェクトスキーマを記述します。直接pathsにオブジェクトスキーマを記述することも可能です。しかし、componentsを使用することでオブジェクトスキーマの共通化を行うことができ、全体のコードの記述量を減らすことが可能です。

components:
  schemas:
    Product:
      type: object
      required:
        - productName
          price
      properties:
        productId:
          type: integer
          description: 商品ID
        productName:
          type: string
          description: 商品名
        price:
          type: integer
          description: 値段
    Products:
      type: array
      items:
        $ref: '#/components/schemas/Product'
    PostProduct:
      type: object
      properties:
        productName:
          type: string
          description: 商品名
        price:
          type: integer
          description: 値段 

おわりに

APIのドキュメント作成自体の経験がなかったのですが、Excelを利用した俗人的なドキュメントよりも、OpenAPIという共通のフォーマットを利用したドキュメントの方が第三者が内容を見ても理解しやすいような印象はあります。現在携わっているプロジェクトではSwaggerを使っており、今後APIを新たに設計する機会もあると思います。その時に備えて、広く活用されているOpenAPIにも慣れていきたいです。