Qiita Teams that are logged in
You are not logged in to any team

Log in to Qiita Team
Community
OrganizationAdvent CalendarQiitadon (β)
Service
Qiita JobsQiita ZineQiita Blog
1
Help us understand the problem. What is going on with this article?
@amyroi

OpenAPI3へのスキーマファースト開発移行(ツール編)

OpenAPI3へのスキーマファースト開発移行(ツール編)

スキーマファースト開発をプロジェクトへ導入してから1年が経ちました。
ツール編では移行の方針や使用ツールについて書いていきます。

Prerequisite :runner:

  • Rails + vue.jsのSPA開発
  • TDD導入済み

Tools :wrench:

Why :question:

  • SPA開発においてAPIとクライアントの開発を行っていましたがチーム開発においてAPI実装への依存度が高かった
  • チームメンバーが増えてくるとAPI仕様の共有や変更の共有にコミュニケーションコストが増えてきた
  • API仕様書を正にして変更があれば自動テストをFailさせたい

Purpose and Rules :triangular_ruler:

  • API・クライアントの実装効率化
  • RESTful API準拠及びOpenAPI3に仕様準拠
  • YAMLで管理
  • API仕様書の分割と結合
  • YAMLのAPI仕様書を読み込み自動テスト(API/クライアント)
  • API仕様書からhtmlドキュメントを生成
  • (モックサーバー起動)

Tools詳細

OpenAPI3

  • OpenAPI3
  • REST-APIの標準仕様であり3系から効率的に記述できるようになっているため3系を使用します
  • docs
  • ドキュメントは英語のみですがサンプルも多く十分理解しやすいです

Swagger Editor

multi-file-swagger

  • multi-file-swagger
  • APIのPathsやComponentを共通化、リポジトリ管理するために分割をしています。分割したYAMLファイルを結合するために使用しています
  • プロジェクトでは自動テスト直前に自動結合させて常に最新の仕様書でテストを走らせています。

OpenAPI Generator

  • OpenAPI Generator
  • API仕様書のhtmlドキュメントを生成するために使用
  • 一部OpenAPI3の構文に対応していない箇所がありOpenAPI Generatorに合わせた書き方をする必要があります。
  • プロジェクトではCIでテストがGreenになったら最新のhtmlドキュメントをS3にアップロードし開発者以外がAPI仕様を閲覧できる状態にしています。

committee

  • committee
  • API仕様書をもとにリクエスト/レスポンス形式をチェックするライブラリです。現在も開発が活発でOpenAPI3に対応したのをきっかけに導入を決めました。

まとめ

  • 次回はスキーマ分割とAPI/クライアントの自動テストを書きたいと思います
1
Help us understand the problem. What is going on with this article?
Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
amyroi
Freelance/Ruby Engineer/Software Engineer/

Comments

No comments
Sign up for free and join this conversation.
Sign Up
If you already have a Qiita account Login
1
Help us understand the problem. What is going on with this article?