sword-cli版本>1.0.0才可以使用生成文档的功能

我们在proto中可以去写这样的多行注释：

  1. /**
  2. * 这是hello接口
  3. * 1
  4. */
  6. export interface ReqParams {
  8. }
  10. export interface ReqQuery {
  11.   /**
  12.   * id
  13.   * 编号
  14.   */
  15.   id: string,
  16.   /**
  17.   * nickname
  18.   * 昵称
  19.   */
  20.   nickname?: string,
  21. }
  23. /**
  24. * 返回的res是一个string
  25. * 这里不用返回其他信息
  26. */
  27. export type Res = string;

多行注释的第一行代表了标题，第二行+第n行代表了介绍
要对接口设置标题和介绍就要在ReqParams上面声明顶级多行注释，同理，如果你返回的类型是一个type（类型别名），那么你也可以使用顶级注释来描述字段。目前仅支持生成以下2种格式：

  • markdown（推荐）
  • openapi（可以导入到apifox，postman中）

使用

当你安装了@swordjs/sword-framework-cli 到全局/项目中时，你可以直接运行此命令，文档将会生成在docs文件夹下

  1. npx sword dev

markdown预览

image.png

openapi格式（导入到apifox中）

image.png

注意事项

  1. 目前使用openapi文档时，需要注意，注释中的第一行（标题）将不会在openapi展现，后续考虑会和第二行（介绍）拼接在说明中一起展示
  2. 如何自定义markdown格式？展示不支持，如果你有需要的话，欢迎提issue

视频教程

点击查看【bilibili】