そのサービスはマイクロですか？こんにちは、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ドキュメントを社内に公開しています。

githubにAPIドキュメントをpushして公開
マイクロサービスのデプロイ環境に公開ページを用意し 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を使用しているので、この機能も有効に使えるよう設定を見直したいと思っています。