Stoplightの使用感がかなり良かった話(OpenAPI,Swagger)

Last updated at 2021-11-26Posted at 2021-11-25

1 / 12

はじめに

Another works サーバサイドエンジニアの釜地です！

みなさんOpenAPI(Swagger)は使用されていますか？
本記事ではOpenAPIを導入するに当たって、合わせて利用して便利だったツールを紹介したいと思います。

そもそもOpenAPI(Swagger)とは？

OpenAPI仕様（以下OAS）と言われるREST APIを定義するための標準仕様にもとづいて構築された一連のオープンソースツールです。
REST APIの設計、構築、文書化、および使用に役立つ機能を提供します。

弊社の課題感

現状、フロントとサーバを分業制で開発している上で下記のような課題がありました。

APIの伝達がJiraのドキュメントであり、フォーマットが統一されず作成するたびに若干書き方が変わる
API仕様が蓄積されていかない

→ 開発チームが大きくなったときのために今の内からドキュメントを残していきたいという想いでOASの導入を行いました。

Stoplight Studio

本家からいくつかツールが提供されていますが、OASを書きやすくしてくれるサードバーティ製の様々なツールが世の中には存在します。
その1つが今回、紹介するStoplight Studioです。
https://stoplight.io/studio/

本来、OASを記載する際はyamlやjson形式で記載する必要があります。
以下記述例
get：/user/{id}でユーザ詳細を取得する

openapi: 3.1.0
info:
  title: user
  version: '1.0'
servers:
  - url: 'http://localhost:3000'
paths:
  '/users/{userId}':
    parameters:
      - schema:
          type: integer
        name: userId
        in: path
        required: true
        description: Id of an existing user.
    get:
      summary: Get User Info by User ID
      tags: []
      responses:
        '200':
          description: ユーザ詳細を取得する
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
              examples:
                Get User Alice Smith:
                  value:
                    id: 142
                    firstName: Alice
                    lastName: Smith
                    email: alice.smith@gmail.com
                    dateOfBirth: '1997-10-31'
                    emailVerified: true
                    signUpDate: '2019-08-24'
        '404':
          description: User Not Found
      operationId: get-users-userId
      description: Retrieve the information of the user with the matching user ID.
components:
  schemas:
    User:
      title: User
      type: object
      description: ''
      examples:
        - id: 142
          firstName: Alice
          lastName: Smith
          email: alice.smith@gmail.com
          dateOfBirth: '1997-10-31'
          emailVerified: true
          signUpDate: '2019-08-24'
      properties:
        id:
          type: integer
          description: Unique identifier for the given user.
        firstName:
          type: string
        lastName:
          type: string
        email:
          type: string
          format: email
        dateOfBirth:
          type: string
          format: date
          example: '1997-10-31'
        emailVerified:
          type: boolean
          description: Set to true if the user's email has been verified.
        createDate:
          type: string
          format: date
          description: The date that the user was created.
      required:
        - id
        - firstName
        - lastName
        - email
        - emailVerified