はじめに
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
このようにyamlファイルは少し書くのが大変かなと思います。
Stoplightはこの課題を解決してくれます。
以下は、上記のyamlファイルをStoplight上で閲覧したものです。
閲覧画面
APIのリクエストやレスポンスのパラメータをかなり見やすく整形してくれます。
また、右側の部分でPostmanみたいに実際の検証環境や開発環境のAPIを叩いて動作を確認することもできます。(めっちゃ便利、、、。)
これだけではなくGUIでAPIのドキュメントを作成して、それらをyaml形式に自動で変換してくれます。
編集画面
かなり直感的に編集できるので記載する工数がかなり削減できるかなと思います!
他の特徴
- 無料(制限はある)
- WEB、バイナリ(Windows、Mac、Linux)として配布
- OpenAPI v2 & v3に対応
- Git連携
- Prismと呼ばれるモックサーバ(後述)を統合
- リアルタイムでLintエラーを表示
Webから簡単に試すことができるので実際に使ってみるのが1番だと思います!
https://stoplight.io/p/studio/gh/stoplightio/studio
まとめ
実際使ってみて、フロントとのコミュニケーションやAPIのレビュー依頼などエンジニア間の連携がやりやすくなったと思っています。
(URLで共有ができるのが良き)
既存APIのドキュメント化が結構大変でしたが、Railsだったらgemを使用すれば既存のコードからyamlを生成できるのでおすすめです。
参考になるリンク貼っておきます。
https://qiita.com/tanish-kr/items/ace80a36ac3cfc060788
Another worksでは一緒に働ける仲間を探しています