Lightning Talk_Stoplightの使用感がかなり良かった話(OpenAPI)

はじめに

Another works サーバサイドエンジニアの釜地です！早いもので入社してから半年がが経過しました。
本記事ではOpenAPIを導入するに当たって、合わせて利用して便利だったツールを紹介したいと思います。

そもそもOpenAPI(Swagger)とは？

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

弊社の課題感

弊社ではフロントとサーバを完全分業制で開発しています。(この規模のスタートアップでは珍しい？)
その中で下記のような課題を抱えていました。

API仕様の伝達がJiraやNotionで行われており、フォーマットが統一されず作成するたびに若干書き方が変わる
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