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