LoginSignup
9
3

More than 1 year has passed since last update.

@ryan5500(Tomoaki Sano)inエンジニアと人生コミュニティ

OpenAPI使い始めるときに全体像を掴みたいので調査

Last updated at Posted at 2022-04-22

背景

OpenAPIについて、個々の記事はあるが、使い始める際の概観記事があんまりなかったので、自分の理解のためにも一度まとめてみた。手を動かせてない箇所もあるので、後々更新する。

OpenAPIとは

  • 特定記法でAPI仕様を書くと、そこからREST APIのコードやドキュメントを生成できるフォーマット
  • コード生成先のプログラミング言語は多い
    • コードジェネレータは選択肢がある
      • 全体として公式swagger-codegenよりもopenapi-generatorのほうがよいらしい

        • OpenAPI generatorを試してみる - Qiita

          もともとSwaggerの時代からSwagger CodeGenとしてコード生成のツールは提供されており今でも利用可能なのですが、どうも開発者同士で反りが合わなかったらしくコミュニティ主導のツールとしてOpenAPI Specificationは誕生しました。

          私が2018年9月頃にSwagger CodeGenを触った感触でやはりSwagger CodeGenはOpenAPI Specification v3.0への対応が遅れていると感じたため、2019年3月現時点でもOASv3.0を利用する場合は様々な言語に対応しているOpenAPI generatorを利用するのが良さそうです。

      • 言語ごとに特性があるのでgoだと別のgeneratorが採用されたりしてる
  • 関連する概念にSwaggerがある、その違いは以下
  • 最新バージョンは3.1.0

開発ツール

  • 本当に使ってよかったOpenAPI (Swagger) ツール | フューチャー技術ブログ

    • Stoplight Studio
      • OpenAPIのフォーマットに精通していなくても、GUIでAPIを作ったらOpenAPIのyamlファイルがexportできるツール
      • マネージドなMockサーバを立てられる
      • 料金体系
    • Prism
      • Stoplight社が出しているOSSモックサーバ、手元でモックサーバとして使える
      • Stoplight Studioで勝手にモックサーバが出来上がるので裏で使ってるのかな
    • Dredd
      • API仕様と実装のズレをテストできる

  • 公式ツール群

    • Swagger-UI
      • OpenAPI Specificationからドキュメントをwebサーバ上で見れるもの, 実態はSPA
    • Swagger-Editor
      • ブラウザ上でOpen API Specificationを書くためのエディタ
      • OpenAPI仕様をyamlでガシガシ書く
      • 最初はStoplight Studioのほうがオススメ
    • Swagger-Codegen
      • OpenAPI Specificationからソースコード生成
      • 上で書いたがopenapi-generatorを使うことが多いかも

  • ReDoc

    • OpenAPI Specificationからhtmlファイルのドキュメント生成
    • サーバ建てずともローカルのhtmlファイルで見れる、CDで静的サイト化できる

OpenAPI Specificationの書き方

開発手法

9
3
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
9
3