Blog

Go製APIで仕様ドキュメントを生成するツールSwagを初めて使ってみてハマったこと

はじめに

ニフティでエンジニアをしている添野 翔太です。
ここ最近、@niftyトップページシステム基盤の刷新を進めていく中で、ニフティの様々なサービスのデータを取得するために、APIをGoで作成していました。
そして、API仕様ドキュメントの管理をどうするか悩む中で、こちらの記事(@pei0804さんに感謝)を見つけ、Swagというツールに着目しました。
本稿ではAPI仕様ドキュメントを生成するSwagを導入した際にハマったことを紹介します。

Swagとは

API仕様定義に基づくツールセットSwaggerに関連するツールであり、Go向けのものとなります。
SwaggerにはYAML形式やJSON形式で記述したAPI仕様定義に基づいてHTMLドキュメントを生成する機能があります。Swagを使うと、コードコメントからYAML形式とJSON形式で記述したAPI仕様定義を生成できます。
コード内に記述するため、ドキュメントの更新漏れリスクを低減させることが可能となります。なお、詳しい記述ルールはSwag公式リポジトリにあるREADMEを参照してください。

実際にSwagを使ってみる

実際にコードコメントからYAML形式とJSON形式のAPI仕様定義を生成してみます。
そのために適当なユーザーの一覧を返却するサンプルAPIを用意しました。
以下は、抽出したいユーザーが所属するサービスの識別子をもとに、ユーザー一覧を返却するAPIのコードです。import文の下とhandler関数の下に、Swagで使用されるコードコメントを記載しています。 さて、API仕様ドキュメントを生成するための準備が揃いましたので生成します。
APIのコード(main.go)が存在するディレクトリで以下のコマンドを入力すると、 構文解析エラーが表示されました。これが本稿の題名にあるハマりポイントでした。 ここでエラーメッセージをもとに調べると、こちらのissueこちらのissueがヒットし、モジュール依存を解決するためのオプションが必要だと判明しました。
そこで、 を実行してみると、今度は上手く行ったようです。 生成されたYAMLファイルを https://editor.swagger.io/ で確認してみると、API仕様ドキュメントを閲覧できました。

おわりに

本稿では、Swagとそれを初めて使ったときにハマったことを紹介しました。
Swagの記述ルールは個人的には分かりやすいと感じていて、導入してみてAPI仕様ドキュメントをすぐに生成できることに感動しました。
皆さんもぜひSwagを使うことを検討してみましょう。

We are hiring!

ニフティでは、さまざまなプロダクトへ挑戦するエンジニアを絶賛募集中です!
ご興味のある方は以下の採用サイトよりお気軽にご連絡ください! Tech TalkやMeetUpも開催しております!
こちらもお気軽にご応募ください!