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

10802 ワード
OpenAPI swagger swagger テキストリンク

はじめに

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: [email protected]
                    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: [email protected]
          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から簡単に試すことができるので実際に使ってみるのが１番だと思います！
https://stoplight.io/p/studio/gh/stoplightio/studio

まとめ

実際使ってみて、フロントとのコミュニケーションやAPIのレビュー依頼などエンジニア間の連携がやりやすくなったと思っています。
(URLで共有ができるのが良き)

既存APIのドキュメント化が結構大変でしたが、Railsだったらgemを使用すれば既存のコードからyamlを生成できるのでおすすめです。

参考になるリンク貼っておきます。
https://qiita.com/tanish-kr/items/ace80a36ac3cfc060788

Another worksでは一緒に働ける仲間を探しています