MuleSoft DesignCenterのAPIドキュメントの作成フロー

[MuleSoft Advent Calendar 2019](!https://qiita.com/advent-calendar/2019/mulesoft)の記事です。

最近追加されたMuleSoftの機能を触ってないので、使ったことのない機能を試してみようと思います。

皆さんAPIのドキュメント何で書いてますか？
WordとかExcelの場合もあるし、RAMLとかYAML、Markdownあたりもあると思いますが、API仕様書って図とかが要らないので、テキストエディタで作って、ソースコードと一緒にgitで管理できるRAML、YAML、Markdownは良いですよね！
ツールもいろいろあって、APIドキュメントを書くのをサポートしてくれるツールや、Webページとして公開できる形にしてくれたります。[Swagger](!https://swagger.io/)とか[API Blueprint](!https://apiblueprint.org/)とか。


Anypoint PlatformのDesign CenterでAPIドキュメントが作成できるので、それをやっていきたいと思います。

## Design Centerにアクセスします
Design CenterはWebブラウザでMuleアプリケーションの開発や、API仕様書の作成ができる機能です。

[Anypoint Platform](https://anypoint.mulesoft.com/home/) にアクセスします。

「Start Designing」を選択します。
<img width="1250" alt="Anypoint Platform 2019-12-19 09-21-09.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/31063/22105c14-8453-ac31-0d1c-cb5141bad166.png">


プロジェクト一覧画面が表示されるので、「Create」でプロジェクトを作成する。
<img width="1251" alt="Design Center 2019-12-19 09-21-51.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/31063/ab91cba9-c721-cee5-cbab-c876169c58b3.png">


アプリケーションを作るか、API仕様書を作るか選べるので、今回はAPI仕様書を作成する「Crate API specification」を選択
<img width="1248" alt="Design Center 2019-12-19 09-22-38.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/31063/c2e5357e-f618-d1f0-8170-58eeb859c185.png">


ドキュメントの記法を選択できます。ここではRAML 1.0を選択します。この記法に沿って書くと、APIのドキュメントがWebで見やすい形になって見れます。
<img width="1248" alt="Design Center 2019-12-19 11-31-34.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/31063/138e9828-a776-9280-c1c7-a8c6dfba3fd5.png">

## Code EditorでAPI仕様を書く
RAMLでAPIの仕様を書いていきます。
RAMLの説明については、こちらの記事が参考になります。
[RAML 200チュートリアル日本語訳](!https://qiita.com/mitch_oka/items/185f0d09a6d20d7e259e)

すでにあるものをImportすることもできます。

<img width="1089" alt="API designer 2019-12-19 11-54-11.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/31063/176068b8-f2e3-1528-701d-367a65df4974.png">


自分で一から書くこともできますが、サンプルも提供されているので、見てみましょう。
<img width="1037" alt="API designer 2019-12-19 11-38-22.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/31063/30accd57-72bb-d341-a9dc-55497a8c92b3.png">

サンプルが結構あるので、参考になりそうなのチェックして、「Import asset」をクリックします。ここでは「Inventory API」を開いてみましょう。
<img width="1125" alt="API designer 2019-12-19 11-39-36.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/31063/c1b97a83-24a3-cb9b-45e0-70081c0e1ce8.png">

こんな感じ。
<img width="1237" alt="API designer 2019-12-19 11-42-12.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/31063/7d825022-dd57-8fb5-931f-ba7353e5cb57.png">

## ドキュメントの公開
ドキュメントの準備ができたら、公開します。**Public**ボタンでExchangeに公開することができます。
<img width="1234" alt="API designer 2019-12-19 11-43-47.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/31063/b5b0afd4-389d-e347-f2dd-22f40ecfa563.png">

どれを公開するのか選んで、「Publish」
<img width="958" alt="API designer 2019-12-19 11-47-46.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/31063/17346ce1-e635-657c-8b40-5b337af9cc27.png">
<img width="955" alt="API designer 2019-12-19 11-45-13.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/31063/b0de8366-0898-c6b8-05a0-299e9ccc5938.png">

## Exchangeで公開された情報を確認

組織（この画面だとNCDC）を選んで、さっき作ったプロジェクトを選択します。

<img width="1238" alt="Anypoint Exchange 2019-12-19 11-48-57.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/31063/e0130edf-5c0f-a5fa-55f2-0da2db888fa5.png">

すると、先程公開したAPIの仕様が公開されています。
APIのモックを呼び出して、APIを試すことができるので、クライアントを作る人はわかりやすいですよね。

<img width="1091" alt="SampleAPISpec 2019-12-19 11-56-55.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/31063/81e3c297-3176-293f-1f81-2f0b7730d61f.png">


## Visual Editor

ちなみに **Visual Editor**を選択するとこんな感じ。
<img width="1249" alt="Design Center 2019-12-19 09-23-55.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/31063/d6ca723e-4d18-3ea6-b72b-79d7819f06d3.png">

まあ実際にはプロジェクトごとにテンプレートになるRAMLファイルを作って、それをベースにCode Editorで作っていくかな。

<img width="1251" alt="API designer 2019-12-19 09-27-31.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/31063/d7ddaf63-6664-2df8-db90-7bb7475c3134.png">

以上です。

## 所感
RAML自体はMuleSoft独自ではなく、オープンな記法なのでそこは良いなと思います。機能的にもAPIを叩いて試せたり便利です。
例えば、Muleアプリや、スクラッチのAPIも含めてRAMLで書いて、必要に応じてExchangeで公開みたいな使い方ができると思います。
基本的にはgitでソースコードとセットで管理するとして、Exchangeで公開するのをCI/CDできるのか別途確認してみたいと思います。

## 参考資料
Design Centerについての公式Doc：[Design Center について](!https://docs.mulesoft.com/jp/design-center/)
Exchangeについての公式Doc：[Exchangeについて](!https://docs.mulesoft.com/jp/exchange/)