写注释已经够折磨开发者了,显然天天curd的我们再去写文档岂不是分分种要被逼疯.
我想每个人都有这种经历
已经有 Swagger
的我们慢慢的已经忘掉了写文档这件事. 但是在某些不方便暴露 swagger
地址的那天,又回忆起被文档支配的恐惧.
showdoc
是一个文档供应商,它提供了一个良好的结构易于开发者编写文档. 也提供了api供开发者自动生成文档. 现在 toshowdoc
把它带到了net core中
toshowdoc
是一个在github上 开源项目 ,来自被文档折磨的我. toshowdoc将swagger的文档转换为showdoc的格式并自动添加与更新,下面介绍一下如何使用toshowdoc自动生成文档
安装之前需要你的机器具有 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 可以看到同步的效果.
写到这里基本已经结束了, toshowdoc
项目刚刚起步,有很多不完善的地方. 欢迎大家吐槽.