---
tags: AsyncAPI
---
# Generating HTML documentation site with AsyncAPI on Windows 10
##### `AsyncAPI` `event-driven APIs` `MQTT`
> [name=Mr. Akashic] [time=Thu, Mar 19, 2021]

## Requirements
* [Node.js v12.16 and higher](https://nodejs.org/en/)
* npm v6.13.7 and higher
* @asyncapi/generator

開啟命令提示字元，輸入指令<span class="dark_orange">npm install -g @asyncapi/generator</span>，安裝<span class="dark_orange">@asyncapi/generator</span>。看到如下資訊表示安裝完成。

npm WARN deprecated request@2.88.2: request has been deprecated, see https://github.com/request/request/issues/3142
npm WARN deprecated har-validator@5.1.5: this library is no longer supported
npm WARN deprecated uuid@3.4.0: Please upgrade  to version 7 or higher.  Older versions may use Math.random() in certain circumstances, which is known to be problematic.  See https://v8.dev/blog/math-random for details.
npm WARN deprecated mkdirp@0.3.5: Legacy versions of mkdirp are no longer supported. Please update to mkdirp 1.x. (Note that the API surface has changed to use Promises in 1.x.)
C:\Users\RCSL\AppData\Roaming\npm\ag -> C:\Users\RCSL\AppData\Roaming\npm\node_modules\@asyncapi\generator\cli.js
C:\Users\RCSL\AppData\Roaming\npm\asyncapi-generator -> C:\Users\RCSL\AppData\Roaming\npm\node_modules\@asyncapi\generator\cli.js
npm WARN optional SKIPPING OPTIONAL DEPENDENCY: fsevents@~2.3.2 (node_modules\@asyncapi\generator\node_modules\rollup\node_modules\fsevents):
npm WARN notsup SKIPPING OPTIONAL DEPENDENCY: Unsupported platform for fsevents@2.3.2: wanted {"os":"darwin","arch":"any"} (current: {"os":"win32","arch":"x64"})
npm WARN @babel/plugin-bugfix-v8-spread-parameters-in-optional-chaining@7.14.5 requires a peer of @babel/core@^7.13.0 but none is installed. You must install peer dependencies yourself.

+ @asyncapi/generator@1.7.3
added 445 packages from 234 contributors in 30.401s

## Implementation
1. 在桌面建立一個專案資料夾，此範例叫asyncapi。
2. 在asyncapi資料夾內建立一個Yaml檔，此範例叫example.yml。
3. 打開example.yml，開始編輯API文件。[官方範例](https://playground.asyncapi.io/?utm_source=editor&utm_medium=editor-topbar&campaign=playground)。編輯完成後儲存。
4. 開啟命令提示字元，使用指令<span class="dark_orange">cd C:\Users\RCSL\Desktop\asyncapi</span>，切換到asyncapi資料夾。資料夾路徑(C:\Users\RCSL\Desktop\asyncapi)請看自己的電腦做修改。
5. 使用指令<span class="dark_orange">ag asyncapi.yml @asyncapi/html-template -o output</span>開始建置API網頁文件。其中，<span class="dark_orange">output</span>為建置完輸出的資料夾名稱，可更改為其他名稱。建置完成後會看如下訊息。

Done! ✨
Check out your shiny new generated files at C:\Users\RCSL\Desktop\asyncapi\output.

:::warning
:warning: **提醒:**
如果是要更新API網頁文件，請使用<span class="dark_orange">ag asyncapi.yml @asyncapi/html-template --force-write output</span>指令，該指令執行完成後，會覆蓋前一次建置的資料夾。
:::
6. 開啟<span class="dark_orange">output</span>資料夾，執行index.html，看到如下頁面(網頁呈現的內容就是在asyncapi.yml編輯的內容)，就完成了本篇記錄的實作。


## Acknowledgements
* [github asyncapi generator](https://github.com/asyncapi/generator)
* [asyncapi generator](https://www.asyncapi.com/generator)
* [asyncapi html-template](https://github.com/asyncapi/html-template)

<style>
.dark_orange {
color: #FF8C00;
background:#F6F6F6;
border-radius:4px;
padding-right:6px;
padding-left:6px;
}

.sub_title {
font-size: 25px;
}

.blockquote {
background:#F6F6F6;
}

</style>