ToShowDoc拯救不想写文档的你

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 项目刚刚起步,有很多不完善的地方. 欢迎大家吐槽.