背景
- 執筆に至った経緯
- 解決すること
概要
- Swaggerとは
目的
- APIの可読性を向上させたい
- APIのドキュメント管理（作成・維持）する手間を削減したい
どのような場面で用いられているのか
- APIの仕様を作成・管理
- バックエンドとフロントの開発を依頼・分担する際に有効
活用方法
まとめ
おわりに
- コメント
参考

背景

執筆に至った経緯

APIの実装に用いられるSwaggerについて調べてみました。

今までは雰囲気で使用していましたが、バックエンドのAPI実装をするにあたってもう少し押さえておこうと思いまとめました。

解決すること

以下の疑問を解消します。

Swaggerとはなにか？
何のために使うのか
実際にどうやって使われるのか

概要

Swaggerとは

「OpenAPI仕様に基づいて構築されたオープンソースツールセットでありREST APIの設計、作成、文書化に役立つツールです。」

Swaggerを仕様するとAPIドキュメントを独自のUIを用いてわかりやすくまとめられます。

目的

APIの可読性を向上させたい

APIエンドポイントやパラメータ、レスポンス形式など、APIに関する情報を簡単に理解することができます。
Swagger UIを使用するとブラウザ上でAPIを実行することができ、認証情報を付与して実際のレスポンスも確認することができます。

APIのドキュメント管理（作成・維持）する手間を削減したい

APIの変更が発生した場合、Swaggerで管理している場合はYAMLファイルでAPI定義を行い、UIを修正してドキュメントを更新することができます。

どのような場面で用いられているのか

APIの仕様を作成・管理

APIのエンドポイントやパラメータ、レスポンス、認証などの詳細な情報を定義し、Swaggerを使用して自動生成されたドキュメントをチェックし、必要に応じて手動で調整することができます。バックエンドエンジニアがこれらを担当することが一般的に多いそう?

バックエンドとフロントの開発を依頼・分担する際に有効

先程の説明の通り、APIエンドポイントやパラメータ、レスポンス形式など、APIに関する情報を効率良く管理・確認することができるため役割分担がしやすいです。
フロントタスクを外注する際にも有効です。Swaggerのドメインを取ってURLをフロントの会社などに共有するなど。その際はVPNなどでアクセス制限し共有されるのが一般的です。

活用方法

【作成・管理】JSONまたはYAMLファイルにAPI情報を定義

APIのエンドポイント、HTTPメソッド、リクエストおよびレスポンスのデータ型、認証、セキュリティなどの詳細な情報を記述したYAMLまたはJSONファイルに記述します。

以下は公式のYAML形式で記載されているサンプルコード例です。

YAMLで記載された内容がドキュメントに反映されます。

サーバー情報もYAMLに記載しておくことで指定したドメインにアクセスすることで確認することが出来ます。

JSONとYAMLはどちらで記述するのが良いか

開発チームの好みや習熟度、プロジェクトの要件によって異なります。

YAML形式は、可読性が高く、インデントによって階層を表現するため、読みやすいファイルを作成することができます。一方、JSON形式は、構造化データの扱いに慣れている場合には、より直感的に理解できる場合があります。

【構築例】Swagger UIでドキュメントを表示

GitHubからUIのソースを持ってきて、独自でカスタマイズすることができます。

https://github.com/swagger-api

YAML形式のAPI定義を読み込んでブラウザで表示する機能を担っています。

【構築例②】Railsで簡単に構築することも出来る (Swagger UI)

１. Gemfileにswagger-blocksとswagger-ui-railsを追加

gem 'swagger-blocks'
gem 'swagger-ui_rails'

２. rails generate swagger:docs コマンドを実行してSwaggerのJSONファイルを生成します。このコマンドを実行すると、/docs/swagger_docs.jsonというファイルが生成されます。このファイルにAPIの仕様を記述します。３. routes.rbファイルに、mount SwaggerUiEngine::Engine, at: "/api-docs"というルーティングを追加します。

Rails.application.routes.draw do
  mount SwaggerUiEngine::Engine, at: "/api-docs"
end

４. Swagger UIを表示するために、http://localhost:3000/api-docsにアクセスします。

上記の方法ではSwagger UIをカスタマイズしたい場合は、swagger-blocksを使用してAPIの仕様を記述する際にカスタマイズすることができますが、Gemを使用せずに独自にSwagger UIのソースをRailsのビューで表示し、YAMLファイルを読み込ませて管理することも可能です。

まとめ

SwaggerはAPI仕様書の管理を最適化するツール
YAMLファイルやJSONファイルに設定を記述することで独自のUIでAPIを管理したり実際に実行することができる
バックエンドとフロントエンドで役割分担する際にとても有用

という内容でした。

おわりに

本記事の内容は以上になります！

Swaggerは現場で非常によく見かけるツールですので、仕組みから理解が出来ると良いと思いました。参考になったり学びのきっかけになりますと幸いです。

間違いがありましたら修正いたしますので、ご指摘ください。

興味があれば他の記事も更新していきますので是非ご覧になってください♪

◇ プログラミングスクールのご紹介 (卒業生より)

https://runteq.jp/r/ohtFwbjW

参考

Swagger 公式 : https://swagger.io/docs/

Swagger Editor : https://editor.swagger.io/

Swagger UI : https://swagger.io/tools/swagger-ui/

GitHub: https://github.com/swagger-api

Yanonoblog!

こつこつと

Swaggerの概要と導入についてまとめてみる

背景