Go製マイクロサービスのAPI仕様をSwaggerで作成、管理する

そのサービスはマイクロですか?
こんにちは、CTO室マイクロサービス推進部でサーバーサイドエンジニアをしている吉岡です。

マイクロサービス推進部ではその名の通り、日々マイクロサービスを開発 / 運用 / 推進しています。
先日リリースしたメール取込もそうですが、私たちの開発しているマイクロサービスはユーザーの皆様に直接触れていただくものではなく、社内の別サービスに機能を提供することが大半です。
提供する機能は主に RESTfulAPI を通して提供しているのですが、仕様(ドキュメント)を明確でわかりやすいものにすることで、チーム間連携をより効率的・効果的に行えるようになります。

本稿では「開発したサービスのAPI仕様をどのように提供するか?」という部分について紹介します。

メール取込に関する概要や目的についてはこちらのEngineersBlogでも紹介していますので、ご興味のある方はご一読ください。

Swaggerって?

早速結論ですが、マイクロサービス推進部ではSwaggerを利用してAPIドキュメントを作成し、サービスの仕様 / 利用方法を社内の別サービスへ提供しています。

Swaggerについては公式ページやわかりやすい解説が数多あると思いますが、ここで簡単に説明させていただくと

コードに記載したコメントからAPIドキュメントを自動生成してくれる便利なフレームワークです。
(正しくはREST API を定義するための仕様を示しますが、本稿ではSwagger-Codegen, Swagger-UIに絞ったドキュメントツールとしての内容を語らせていただきます)

なぜSwaggerなのか?

仕様書や設計書を書く機会は多いと思いますが、数が増えれば増えるほどメンテナンスが大変になりますよね。

  • APIについて仕様書が複数ある
  • 最新の仕様に更新する
  • そもそも仕様書を書いていたか
  • etc…

Swaggerを導入すると、コードとは別にAPIの仕様書を書く必要がなくなり、コードと仕様書を一対一で管理、維持できます。
コードに所定のフォーマットでリクエストパスやパラメータを記載すると、その記載を元にAPIドキュメント(json,yamlファイル)をコマンド一つで自動生成してくれるのです(仕様を書かなくていいわけではありません…)。
Swaggerで生成されたAPIドキュメントはSwagger-UI(生成されたAPIドキュメントをいい感じに可視化するツール)で閲覧する前提になります。

他にもSwaggerの提供する機能はありますが、マイクロサービス推進部では実装とAPI仕様をまとめて管理できるようSwaggerを導入することを決めました。

マイクロサービス推進部での導入例

実際にどのようにして APIドキュメントを作成、公開するのかを簡単にご説明します。

APIドキュメントの作成

まずはドキュメントを作成するため、RESTfulAPIのパスやパラメータ、応答のモデルなどをコード上にアノテーションで記載していきます。
(マイクロサービス推進部ではGoでサービスを実装しているため、GoからAPIドキュメントを生成するライブラリswaggo/swagを利用しています)

// Param apiパラメータ
type Param struct {
    ID string // ユーザーID
}

// Account アカウントの情報
type Account struct {
    Name   string // アカウント名
    Status int    // アカウントのステータス
}

// GetAccount
// @summary アカウントの情報を返します
// @description user_idを元にアカウント情報を返します
// @tags accounts
// @produce json
// @param user_id query int false "user_id"
// @success 200 {object} Account
// @failure 401 {object} Error
// @router /accounts [get]
func (c *Controller) GetAccount(ctx echo.Context) error {
    // ...implement
}
// @title sample api
// @version 1.0
// @description this is sample apigw

// @host localhost:18080
// @BasePath /api/v1

// @tag.name accounts
// @tag.description about accounts request
func main() {
    // ...implement
}

次にコマンドラインから生成コマンドを実行します。

$ swag init \
> --dir <apiドキュメントを作成したいコードのパス> \
> --output <apiドキュメントの作成先> \

文にするとたったこれだけです。簡単ですね。

APIドキュメントの公開(社内向け)

マイクロサービス推進部では2つの方法でAPIドキュメントを社内に公開しています。

  1. githubにAPIドキュメントをpushして公開
  2. マイクロサービスのデプロイ環境に公開ページを用意し Swagger-UI を提供する

1の方法は、githubにアップしたAPIドキュメントをブラウザで参照してもらう方法です。
APIドキュメントをgithubへアップするだけで良いので、開発者は楽にAPI仕様を公開することができます。
と言っても、APIドキュメントはただのjson/yamlファイルなので、閲覧者はブラウザに拡張機能(swagger-viewer)を入れるなどして閲覧する必要があります。

2の方法は、Swagger-UIをデプロイ環境の1URLとして公開する方法です。
閲覧者は、公開ページのURLさえ知っていれば下図のようにSwagger-UIで可視化されたAPIモデルを閲覧することができます。

今後改善したい点

ドキュメントの自動生成/更新

現状はAPIドキュメントを作成 / 更新する際には、開発者が生成コマンドの実行生成ファイルをcommit,pushしています。
生成コマンドはほぼ固定なので、API仕様に変更があれば自動でAPIドキュメントを再作成する仕組みを入れたいと思っています。

Swagger-UIからのリクエスト送信

Swagger-UI上では、Httpリクエストを組み立て、実際にリクエストを送信することもできます。
APIの動作確認や、使用感を簡単につかむことができて便利なのですが、Dev環境やStg環境には認証機能が必要であるため、まだ対応できていません(正しく設定することで認証をパスできます)。
せっかくSwagger-UIを使用しているので、この機能も有効に使えるよう設定を見直したいと思っています。

まとめ

マイクロサービス推進部でのAPI仕様の提供とSwaggerの利用について紹介しました。
まだ使い切れていない部分もありますが、少しでも面倒な手間は減らして、サービスの向上に時間を使えるようこれからも外部ツールの利用や自動化を進めていこうと思います。

マイクロサービス推進部ではマイクロサービスの開発と共に、Swagger以外にもGithub Actionsや自作ツールなどで作業を自動化する取り組みも進めています。

開発メンバーを募集していますので、ご興味を持っていただけた方は一度カジュアル面談でお話ししませんか?
CTO室エンジニアの募集


マネーフォワードでは、エンジニアを募集しています。
ご応募お待ちしています。

【サイトのご案内】
マネーフォワード採用サイト
Wantedly
京都開発拠点

【プロダクトのご紹介】
お金の見える化サービス 『マネーフォワード ME』 iPhone,iPad Android

ビジネス向けバックオフィス向け業務効率化ソリューション 『マネーフォワード クラウド』

おつり貯金アプリ 『しらたま』

お金の悩みを無料で相談 『マネーフォワード お金の相談』

だれでも貯まって増える お金の体質改善サービス 『マネーフォワード おかねせんせい』

金融商品の比較・申し込みサイト 『Money Forward Mall』

くらしの経済メディア 『MONEY PLUS』

Pocket