1
/
5

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

このようにyamlファイルは少し書くのが大変かなと思っています。
Stoplightはこの課題を解決してくれます。

StoplightでのAPI閲覧画面

上記のようにAPIのリクエストやレスポンスのパラメータをかなり見やすく整形してくれます。
また、右側の部分でPostmanみたいに検証環境や開発環境のAPIを叩いて動作を確認することもできます。(めっちゃ便利、、、。)

これだけではなくGUIでAPIのドキュメントを作成し、それをyaml形式に自動で変換してくれます。

StoplightでのAPI編集画面

かなり直感的に編集ができて、記載する工数も削減できるかなと思います!

他の特徴

  • 無料(制限はある)
  • 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では一緒に働ける仲間を探しています

弊社では今回紹介したREST APIだけでなく、サーバ間通信としてgRPCを利用しています!
技術面でもチャレンジングな環境ですので是非一緒に働きましょう!

インターン/オープンポジション
総額6.5億円シリーズB調達完了/長期インターンとして力を貸してください!
Another worksは『挑戦する全ての人の機会を最大化する』VISIONの実現に向けて 複業したい方と企業を繋ぐプラットフォーム「複業クラウド」を運営しています。 ■複業クラウドの特徴 ◎創業以来変わらない想いとプロダクト 2019年の創業以来一貫して『複業クラウド』を提供しており、現在は45,000名にご利用いただき、導入企業も1,000社を超える急成長を遂げています。(2022年10月末時点) 『挑戦する全ての人の機会を最大化する』VISION実現に向けて、事業ピポットすることなくご利用企業/個人双方にとって良いプロダクトを開発し続けております。 ◎手数料や中間マージンが無料 人材業界の常識を覆す。通常であれば紹介手数料50万円〜100万円や、中間マージン30〜50%が発生する中、企業と個人が直接契約ができるサービスをSaaSで提供しています。専属のCSが採用成功に向けて伴走することで、複業人材の採用成功率は80%以上です。 ◎新規事業展開 新たな市場創造に向けて今後の柱となる新規事業をforシリーズとして展開しております。 ▼複業クラウドfor Public - 地方自治体様×複業人材 ▼複業クラウドfor Sports - スポーツ団体様×複業人材 ▼複業クラウドfor Academy - 学校法人様×複業人材 ▼複業クラウドfor Professional - 企業様×プロ複業人材 ■Another worksの特徴 ◎社員について 年代:20代が中心 平均年齢:27歳 社員数:40名 男女比:7:3 ◎社員出身企業 ビズリーチ / リクルート / パーソル / パソナ / ベネフィット・ワン / レバレジーズ / マイナビワークス / ディップ / DONUTS(ジョブカン)etc
株式会社Another works
エンタープライズCS
総額6.5億円シリーズB調達完了/人材業界を変えるエンプラCSを募集!
Another worksは『挑戦する全ての人の機会を最大化する』VISIONの実現に向けて 複業したい方と企業を繋ぐプラットフォーム「複業クラウド」を運営しています。 ■複業クラウドの特徴 ◎創業以来変わらない想いとプロダクト 2019年の創業以来一貫して『複業クラウド』を提供しており、現在は45,000名にご利用いただき、導入企業も1,000社を超える急成長を遂げています。(2022年10月末時点) 『挑戦する全ての人の機会を最大化する』VISION実現に向けて、事業ピポットすることなくご利用企業/個人双方にとって良いプロダクトを開発し続けております。 ◎手数料や中間マージンが無料 人材業界の常識を覆す。通常であれば紹介手数料50万円〜100万円や、中間マージン30〜50%が発生する中、企業と個人が直接契約ができるサービスをSaaSで提供しています。専属のCSが採用成功に向けて伴走することで、複業人材の採用成功率は80%以上です。 ◎新規事業展開 新たな市場創造に向けて今後の柱となる新規事業をforシリーズとして展開しております。 ▼複業クラウドfor Public - 地方自治体様×複業人材 ▼複業クラウドfor Sports - スポーツ団体様×複業人材 ▼複業クラウドfor Academy - 学校法人様×複業人材 ▼複業クラウドfor Professional - 企業様×プロ複業人材 ■Another worksの特徴 ◎社員について 年代:20代が中心 平均年齢:27歳 社員数:40名 男女比:7:3 ◎社員出身企業 ビズリーチ / リクルート / パーソル / パソナ / ベネフィット・ワン / レバレジーズ / マイナビワークス / ディップ / DONUTS(ジョブカン)etc
株式会社Another works
フロントエンジニア
複業クラウドをReactで開発するフロントエンジニア募集
Another worksは『挑戦する全ての人の機会を最大化する』VISIONの実現に向けて 複業したい方と企業を繋ぐプラットフォーム「複業クラウド」を運営しています。 ■複業クラウドの特徴 ◎創業以来変わらない想いとプロダクト 2019年の創業以来一貫して『複業クラウド』を提供しており、現在は45,000名にご利用いただき、導入企業も1,000社を超える急成長を遂げています。(2022年10月末時点) 『挑戦する全ての人の機会を最大化する』VISION実現に向けて、事業ピポットすることなくご利用企業/個人双方にとって良いプロダクトを開発し続けております。 ◎手数料や中間マージンが無料 人材業界の常識を覆す。通常であれば紹介手数料50万円〜100万円や、中間マージン30〜50%が発生する中、企業と個人が直接契約ができるサービスをSaaSで提供しています。専属のCSが採用成功に向けて伴走することで、複業人材の採用成功率は80%以上です。 ◎新規事業展開 新たな市場創造に向けて今後の柱となる新規事業をforシリーズとして展開しております。 ▼複業クラウドfor Public - 地方自治体様×複業人材 ▼複業クラウドfor Sports - スポーツ団体様×複業人材 ▼複業クラウドfor Academy - 学校法人様×複業人材 ▼複業クラウドfor Professional - 企業様×プロ複業人材 ■Another worksの特徴 ◎社員について 年代:20代が中心 平均年齢:27歳 社員数:40名 男女比:7:3 ◎社員出身企業 ビズリーチ / リクルート / パーソル / パソナ / ベネフィット・ワン / レバレジーズ / マイナビワークス / ディップ / DONUTS(ジョブカン)etc
株式会社Another works
株式会社Another worksでは一緒に働く仲間を募集しています
5 いいね!
5 いいね!
同じタグの記事
今週のランキング
株式会社Another worksからお誘い
この話題に共感したら、メンバーと話してみませんか?