ToShowDoc拯救不想寫文檔的你
寫注釋已經夠折磨開發者了,顯然天天curd的我們再去寫文檔豈不是分分種要被逼瘋.
我想每個人都有這種經歷
- 加了一個參數文檔忘了更新
- 參數名更改文檔忘了更新
- 刪掉一個接口文檔忘了更新
- ....... 各種忘了更新
已經有Swagger的我們慢慢的已經忘掉了寫文檔這件事. 但是在某些不方便暴露swagger地址的那天,又回憶起被文檔支配的恐懼.
What is ToShowDoc
showdoc是一個文檔供應商,它提供了一個良好的結構易於開發者編寫文檔. 也提供了api供開發者自動生成文檔. 現在toshowdoc把它帶到了net core中
toshowdoc是一個在github上開源項目,來自被文檔折磨的我. toshowdoc將swagger的文檔轉換為showdoc的格式並自動添加與更新,下面介紹一下如何使用toshowdoc自動生成文檔
GetStart
安裝之前需要你的機器具有netcore環境,如果沒有請去官方下載並安裝
使用cmd鍵入以下命令
dotnet tool install -g toshowdoc
基本命令
toshowdoc add 添加一個項目
toshowdoc update 更新項目信息
toshowdoc del 刪除一個項目
toshowdoc list 顯示項目集合
toshowdoc sync 同步項目文檔
toshowdoc -h 顯示幫助信息
用法可參考-h的幫助信息,例如添加
toshowdoc add -h
現在下載位於github的示例項目,使用vs打開解決方案並且運行BookStore.Core3.x項目.vs會使用iis express運行項目
運行以下命令
toshowdoc add -n bookstore3.x -ak a338fb0d83c6f4b660bc2706b92e89451844587564 -at e1511a84db06d25150377970f328e9f7572510835 -su https://localhost:44383/swagger/v1/swagger.json -sdu https://www.showdoc.cc/server/api/item/updateByApi
這時已經添加了一個項目到toshowdoc中,可以運行list命令進行查看
toshowdoc list
現在可以使用sync同步文檔, 同步后屏幕會輸出 Successfully! 代表同步成功
toshowdoc sync -n bookstore3.x
這時訪問 https://www.showdoc.cc/531990815627886 可以看到同步的效果.
the end
寫到這里基本已經結束了, toshowdoc 項目剛剛起步,有很多不完善的地方. 歡迎大家吐槽.