除了swagger，你还用过哪几个在线文档生成器

1、gitbook

github地址：https://github.com/GitbookIO/gitbook

开发语言：javascript

示例地址：https://www.servicemesher.com/envoy/intro/arch_overview/dynamic_configuration.html

gitBook是一款文档编辑工具。它的功能类似金山WPS中的word或者微软office中的word的文档编辑工具。它可以用来写文档、建表格、插图片、生成pdf。当然，以上的功能WPS、office可能做得更好，但是，gitBook还有更最强大的功能：它可以用文档建立一个网站，让更多人了解你写的书，另外，最最核心的是，他支持Git，也就意味着，它是一个分布式的文档编辑工具。你可以随时随地来编写你的文档，也可以多人共同编写文档，哪怕多人编写同一页文档，它也能记录每个人的内容，然后告诉你他们之间的区别，也能记录你的每一次改动，你可以查看每一次的书写记录和变化，哪怕你将文档都删除了，它也能找回来！这就是它继承git后的厉害之处！

优点

使用起来非常简单，支持全文搜索，可以跟git完美集成，对代码无任何嵌入性，支持markdown格式的文档编写。
缺点

需要单独维护一个文档项目，如果接口修改了，需要手动去修改这个文档项目，不然可能会出现接口和文档不一致的情况。并且，不支持在线调试功能。

个人建议：如果对外的接口比较少，或者编写之后不会经常变动可以用这个。

2、knife4j

介绍

gitee地址：https://gitee.com/xiaoym/knife4j

开发语言：java、javascript

示例地址：http://swagger-bootstrap-ui.xiaominfo.com/doc.html

knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案,前身是swagger-bootstrap-ui,取名kni4j是希望她能像一把匕首一样小巧,轻量,并且功能强悍。

优点

基于swagger生成实时在线文档，支持在线调试，全局参数、国际化、访问权限控制等，功能非常强大。
缺点

界面有一点点丑，需要依赖额外的jar包

个人建议：如果公司对ui要求不太高，可以使用这个文档生成工具，比较功能还是比较强大的。

给swagger换上新皮肤

knife4j是swagger的增强版，我们在springboot项目使用knife4j，只需两步

第1步，导入依赖

<!--整合Knife4j-->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>2.0.4</version>
</dependency>

第2步，Swagger2Config中增加一个@EnableKnife4j注解，开启knife4j的增强功能

/**
 * Swagger2API文档的配置
 */
@Configuration
@EnableSwagger2
@EnableKnife4j
public class Swagger2Config {
    
}

访问http://localhost:8088/doc.html

功能增强点

返回结果集支持折叠
请求参数有JSON校验功能
支持在头部增加token，用于登录认证

首先在Authorize功能中添加登录返回的Token

之后在每个接口中的请求头中携带了Token信息
离线文档

我最喜欢这个了，以后就不用写markdown的前端接口文档了

直接选择文档管理->离线文档功能，然后选择下载Markdown即可；

我们来查看下导出的Markdown离线文档，还是很详细的

全局参数

支持两种类型：query表单和header请求头

比如我们想要在所有请求头中加入一个参数appType来区分是android还是ios调用，可以在全局参数中添加

此时再调用接口时，请求头就会包含appType这个参数

忽略参数属性

场景：有时候我们创建和修改的接口会使用同一个对象作为请求参数，但是我们创建的时候并不需要id，而修改的时候会需要id，此时我们可以忽略id这个属性。

比如这里的创建商品接口，id、商品数量、商品评论数量都可以让后台接口生成无需传递，可以使用knife4j提供的@ApiOperationSupport注解来忽略这些属性；

/**
 * 品牌管理Controller
 * Created by macro on 2019/4/19.
 */
@Api(tags = "PmsBrandController", description = "商品品牌管理")
@Controller
@RequestMapping("/brand")
public class PmsBrandController {
    @Autowired
    private PmsBrandService brandService;
  
    private static final Logger LOGGER = LoggerFactory.getLogger(PmsBrandController.class);
  
    @ApiOperation("添加品牌")
    @ApiOperationSupport(ignoreParameters = {"id","productCount","productCommentCount"})
    @RequestMapping(value = "/create", method = RequestMethod.POST)
    @ResponseBody
    public CommonResult createBrand(@RequestBody PmsBrand pmsBrand) {
        CommonResult commonResult;
        int count = brandService.createBrand(pmsBrand);
        if (count == 1) {
            commonResult = CommonResult.success(pmsBrand);
            LOGGER.debug("createBrand success:{}", pmsBrand);
        } else {
            commonResult = CommonResult.failed("操作失败");
            LOGGER.debug("createBrand failed:{}", pmsBrand);
        }
        return commonResult;
    }
}

此时查看接口文档时，发现这三个属性已经消失，这样前端开发查看接口文档时就不会觉得你定义无用参数了，是不很很好的功能！

参考资料：官方文档：https://doc.xiaominfo.com/guide/

项目源码：https://github.com/macrozheng/mall-learning/tree/master/mall-tiny-knife4j

3、yapi

github地址：https://github.com/YMFE/yapi

开发语言：javascript

示例地址：http://swagger-bootstrap-ui.xiaominfo.com/doc.html

yapi是去哪儿前端团队自主研发并开源的，主要支持以下功能：

可视化接口管理
数据mock
自动化接口测试
数据导入（包括swagger、har、postman、json、命令行）
权限管理
支持本地化部署
支持插件
支持二次开发

优点

功能非常强大，支持权限管理、在线调试、接口自动化测试、插件开发等，BAT等大厂等在使用，说明功能很好。

缺点

在线调试功能需要安装插件，用户体检稍微有点不好，主要是为了解决跨域问题，可能有安全性问题。不过要解决这个问题，可以自己实现一个插件，应该不难

4、apidoc

github地址：https://github.com/apidoc/apidoc

开发语言：javascript

示例地址：https://apidocjs.com/example/#api-User

apidoc 是一个简单的 RESTful API 文档生成工具，它从代码注释中提取特定格式的内容生成文档。支持诸如 Go、Java、C++、Rust 等大部分开发语言，具体可使用 apidoc lang 命令行查看所有的支持列表。

优点

基于代码注释生成在线文档，对代码的嵌入性比较小，支持多种语言，跨平台，也可自定义模板。支持搜索和在线调试功能。
缺点

需要在注释中增加指定注解，如果代码参数或类型有修改，需要同步修改注解相关内容，有一定的维护工作量。

个人建议：这种在线文档生成工具提供了另外一种思路，swagger是在代码中加注解，而apidoc是在注解中加数据，代码嵌入性更小，推荐使用。

5、showdoc

github地址：https://github.com/star7th/showdoc

开发语言：javascript、php

示例地址：https://www.showdoc.com.cn/demo?page_id=9

ShowDoc就是一个非常适合IT团队的在线文档分享工具，它可以加快团队之间沟通的效率。

它都有些什么功能：

响应式网页设计，可将项目文档分享到电脑或移动设备查看。同时也可以将项目导出成word文件，以便离线浏览。
权限管理，ShowDoc上的项目有公开项目和私密项目两种。公开项目可供任何登录与非登录的用户访问，而私密项目则需要输入密码验证访问。密码由项目创建者设置。
ShowDoc采用markdown编辑器，点击编辑器上方的按钮可方便地插入API接口模板和数据字典模板。
ShowDoc为页面提供历史版本功能，你可以方便地把页面恢复到之前的版本。
支持文件导入，文件可以是postman的json文件、swagger的json文件、showdoc的markdown压缩包，系统会自动识别文件类型。

优点

支持项目权限管理，多种格式文件导入，全文搜索等功能，使用起来还是非常方便的。并且既支持部署自己的服务器，也支持在线托管两种方式。
缺点

不支持在线调试功能

个人建议：如果不要求在线调试功能，这个在线文档工具值得使用。

6、smartdoc

简介

使用swagger需要用到它的注解如@Api 、@ApiOperation、@ApiModel、@ApiParam，swagger通过这些注解生成Api文档，会对代码有入侵性，也会与代码注释有点重复。而smart-doc可以根据代码注释生成api文档，无需写api注解

官方文档：https://gitee.com/smart-doc-team/smart-doc/wikis/HOME

参考:https://github.com/macrozheng/mall-learning/tree/master/mall-tiny-smart-doc

生成API文档

接下来我们把smart-doc集成到SpringBoot项目中，体验一下它的API文档生成功能。

1) 首先我们需要在项目中添加smart-doc的Maven插件，可以发现smart-doc就是个插件，连依赖都不用添加，真正零入侵啊；

<plugin>
    <groupId>com.github.shalousun</groupId>
    <artifactId>smart-doc-maven-plugin</artifactId>
    <version>2.2.8</version>
    <configuration>
        <!--指定smart-doc使用的配置文件路径-->
        <configFile>./src/main/resources/smart-doc.json</configFile>
        <!--指定项目名称-->
        <projectName>mall-tiny-smart-doc</projectName>
    </configuration>
</plugin>

2) 接下来在项目的resources目录下，添加配置文件smart-doc.json，属性说明直接参考注释即可

   {
     "serverUrl": "http://localhost:8088", //指定后端服务访问地址
     "outPath": "src/main/resources/static/doc", //指定文档的输出路径，生成到项目静态文件目录下，随项目启动可以查看
     "isStrict": false, //是否开启严格模式
     "allInOne": true, //是否将文档合并到一个文件中
     "createDebugPage": false, //是否创建可以测试的html页面
     "packageFilters": "com.macro.mall.tiny.controller.*", //controller包过滤
     "style":"xt256", //基于highlight.js的代码高设置
     "projectName": "mall-tiny-smart-doc", //配置自己的项目名称
     "showAuthor":false, //是否显示接口作者名称
     "allInOneDocFileName":"index.html" //自定义设置输出文档名称
   }

打开IDEA的Maven面板，双击smart-doc插件的smart-doc:html按钮，即可生成API文档；

此时我们可以发现，在项目的static/doc目录下已经生成如下文件；
运行项目，访问生成的API接口文档，发现文档非常详细，包括了请求参数和响应结果的各种说明，访问地址：http://localhost:8088/doc/index.html

我们回过来看下实体类的代码，可以发现我们只是规范地添加了字段注释，生成文档的时候就自动有了；

public class PmsBrand implements Serializable {
    /**
     * ID
     */
    private Long id;

    /**
     * 名称
     * @required
     */
    private String name;

    /**
     * 首字母
     * @since 1.0
     */
    private String firstLetter;

    /**
     * 排序
     */
    private Integer sort;

    /**
     * 是否为品牌制造商(0,1)
     */
    private Integer factoryStatus;

    /**
     * 显示状态(0,1)
     * @ignore
     */
    private Integer showStatus;

    /**
     * 产品数量
     */
    private Integer productCount;

    /**
     * 产品评论数量
     */
    private Integer productCommentCount;

    /**
     * 品牌logo
     */
    private String logo;

    /**
     * 专区大图
     */
    private String bigPic;

    /**
     * 品牌故事
     */
    private String brandStory;
    //省略getter、setter方法
}

再来看下Controller中代码，我们同样规范地在方法上添加了注释，生成API文档的时候也自动有了

/**
 * 商品品牌管理
 */
@Controller
@RequestMapping("/brand")
public class PmsBrandController {
    @Autowired
    private PmsBrandService brandService;
    
    /**
     * 分页查询品牌列表
     *
     * @param pageNum 页码
     * @param pageSize 分页大小
     */
    @RequestMapping(value = "/list", method = RequestMethod.GET)
    @ResponseBody
    @PreAuthorize("hasRole('ADMIN')")
    public CommonResult<CommonPage<PmsBrand>> listBrand(@RequestParam(value = "pageNum", defaultValue = "1")
                                                                Integer pageNum,
                                                        @RequestParam(value = "pageSize", defaultValue = "3")
                                                                Integer pageSize) {
        List<PmsBrand> brandList = brandService.listBrand(pageNum, pageSize);
        return CommonResult.success(CommonPage.restPage(brandList));
    }
}

smart-doc还提供了自定义注释tag，用于增强文档功能

@ignore：生成文档时是否要过滤该属性；
@required：用于修饰接口请求参数是否必须；
@since：用于修饰接口中属性添加的版本号

为了写出优雅的API文档接口，我们经常会对返回结果进行统一封装，smart-doc也支持这样的设置，在smart-doc.json中添加如下配置即可；
```
{
  "responseBodyAdvice":{ //统一返回结果设置
    "className":"com.macro.mall.tiny.common.api.CommonResult" //对应封装类
  }
}
```

我们也经常会用枚举类型来封装状态码，在smart-doc.json中添加如下配置即可；

{
  "errorCodeDictionaries": [{ //错误码列表设置
    "title": "title",
    "enumClassName": "com.macro.mall.tiny.common.api.ResultCode", //错误码枚举类
    "codeField": "code", //错误码对应字段
    "descField": "message" //错误码描述对应字段
  }]
}

配置成功后，即可在API文档中生成错误码列表；

有时候我们也会想给某些接口添加自定义请求头，比如给一些需要登录的接口添加Authorization头，在smart-doc.json中添加如下配置即可；

{
  "requestHeaders": [{ //请求头设置
    "name": "Authorization", //请求头名称
    "type": "string", //请求头类型
    "desc": "token请求头的值", //请求头描述
    "value":"token请求头的值", //请求头的值
    "required": false, //是否必须
    "since": "-", //添加版本
    "pathPatterns": "/brand/**", //哪些路径需要添加请求头
    "excludePathPatterns":"/admin/login" //哪些路径不需要添加请求头
  }]
}

配置成功后，在接口文档中即可查看到自定义请求头信息了。

使用postman测试接口

我们使用Swagger生成文档时候，是可以直接在上面测试接口的，而smart-doc的接口测试能力真的很弱，这也许是它拥抱Postman的原因吧

smart-doc内置了Postman的json生成插件，可以一键生成并导入到Postman中去，双击smart-doc:postman按钮即可生成；
此时将在项目的static/doc目录下生成postman.json文件；
将postman.json文件直接导入到Postman中即可使用；

导入成功后，所有接口都将在Postman中显示，这下我们可以愉快地测试接口了！

总结

smart-doc确实是一款好用的API文档生成工具，尤其是它零注解侵入的特点。虽然它的接口测试能力有所不足，但是可以一键生成JSON文件并导入到Postman中去，使用起来也是非常方便的！

7、Torna

简介

跟yapi相似，Torna是一个企业级饿的接口文档解决方案，可以配合swagger实用，它具有如下功能：

文档管理：支持接口文档增删改查、接口调试、字典管理及导入导出功能；
权限管理：支持接口文档的权限管理，同时有访客、开发者、管理员三种角色；
双模式：独创的双模式，管理模式可以用来编辑文档内容，浏览模式纯粹查阅文档，界面无其它元素干扰。

项目架构

Torna是一个前后端分离项目，后端使用SpringBoot+MyBatis来实现，前端使用Vue+ElementUI来实现，技术栈非常主流！它不仅可以搭建API文档网站，还是个非常好的学习项目，让我们先来看看它的项目架构。

首先我们需要下载Torna的源码，下载地址：https://gitee.com/durcframework/torna
下载成功后，将代码导入到IDEA中，项目结构如下，直接通过git clone 拉下来就行
我们再来看下server模块的结构，一个非常标准的SpringBoot项目
再来看下front模块的结构，一个非常标准的Vue项目，值得学习！

运行部署

Windows

后端运行

首先创建一个数据库torna，然后导入项目中的mysql.sql脚本，导入成功后，表结构如下；

修改项目的配置文件server/boot/src/main/resources/application.properties，修改对应的数据库连接配置

# Server port
server.port=7700
  
# MySQL host
mysql.host=localhost:3306
# Schema name
mysql.schema=torna
# Insure the account can run CREATE/ALTER sql.
mysql.username=root
mysql.password=root

然后运行项目启动类TornaApplication的main方法，控制台打印如下信息表示启动成功

前端运行

进入前端项目目录front，运行npm install命令安装依赖；

这个nom 是依赖nodejs环境的，所以要先在服务器上安装nodejs

此时如果遇到node-sass无法安装的情况，可以直接使用如下命令安装；
```
npm i node-sass --sass_binary_site=https://npm.taobao.org/mirrors/node-sass/
```
依赖安装完成后，可以通过npm run dev命令启动项目，启动成功后访问地址：http://localhost:9530/
通过体验账号密码admin@torna.cn:123456可以访问Torna服务，界面还是不错的！

Linux

在Linux下使用Docker安装Torna是非常简单的，如果你只想用Torna来做API文档服务的话可以采用这种方式。

拉取docker镜像
```
docker pull tanghc2020/torna:latest
```

下载完成后将配置文件application.properties拷贝配置文件到/mydata/torna/config目录下，并修改数据库配置；

# Server port
server.port=7700
  
# MySQL host
mysql.host=192.168.3.101:3306
# Schema name
mysql.schema=torna
# Insure the account can run CREATE/ALTER sql.
mysql.username=root
mysql.password=root

然后通过docker命令运行Torna服务，注意需要使用 -v 做容器目录挂载到宿主机上，方便修改配置文件
```
docker run -p 7700:7700 --name torna \
-v /mydata/torna/config:/torna/config \
-d tanghc2020/torna:latest
```
由于镜像中直接包含了前端和后端项目，所以可以直接使用，访问地址：http://192.168.3.101:7700

其实这个就是容器内前端项目的地址，它把请求转发到容器里的后端项目了

使用

Torna支持从多种工具导入接口文档，包括Swagger、smart-doc、OpenAPI、Postman等，接下来我们来体验下它的功能！

Torna能大大增强Swagger的功能，并且界面足够美观，下面我们来体验下！

在使用之前，我们需要在Torna中进行配置才行，首先我们来配置一个开放用户，新建一个macro的账号，记住AppKey和Secret；
然后创建一个项目mall-tiny-trona；
接下来创建一个模块，打开OpenAPI标签，获取请求路径和token；

之后在使用Swagger的项目中集成Torna插件，非常简单，添加如下依赖即可；

<!-- Torna Swagger 插件 -->
<dependency>
    <groupId>cn.torna</groupId>
    <artifactId>swagger-plugin</artifactId>
    <version>1.2.6</version>
    <scope>test</scope>
</dependency>

然后在resources目录下添加配置文件torna.json，配置说明参考注释即可；

{
  // 开启推送
  "enable": true,
  // 扫描package，多个用;隔开
  "basePackage": "com.macro.mall.tiny.controller",
  // 推送URL，IP端口对应Torna服务器
  "url": "http://localhost:7700/api",
  // appKey
  "appKey": "20211103905498418195988480",
  // secret
  "secret": "~#ZS~!*2B3I01vbW0f9iKH,rzj-%Xv^Q",
  // 模块token
  "token": "74365d40038d4f648ae65a077d956836",
  // 调试环境，格式：环境名称,调试路径，多个用"|"隔开
  "debugEnv": "test,http://localhost:8088",
  // 推送人
  "author": "macro",
  // 打开调试:true/false
  "debug": true,
  // 是否替换文档，true：替换，false：不替换（追加）。默认：true
  "isReplace": true
}

接下来通过调用SwaggerPlugin的pushDoc方法来推送接口文档到Torna；

@RunWith(SpringRunner.class)
@SpringBootTest
public class MallTinyApplicationTests {
  
    @Test
    public void pushDoc(){
        // 将文档推送到Torna服务中去，默认查找resources下的torna.json
        SwaggerPlugin.pushDoc();
    }
}

推送成功后，在接口列表将显示如下接口信息；
查看一下接口的详细信息，还是很全面的，界面也不错！
把我们的项目运行起来，就可以直接在上面进行接口调试了，调用下登录接口试试；
如果我们想设置公共请求头的话，比如用于登录认证的Authorization头，可以在模块配置中进行配置；
在后端接口没有完成前，我们如果需要Mock数据的话，可以使用Mock功能
这里我们对登录接口进行了一下Mock，当然你也可以使用Mock脚本，这下只要接口定义好，前端就可以使用Mock的数据联调了。

结合smart-doc使用

首先修改mall-tiny-smart-doc项目的smart-doc配置文件smart-doc.json，添加如下关于Torna的配置；

{
  // torna平台对接appKey
  "appKey": "20211103905498418195988480",
  //torna平台appToken
  "appToken": "b6c50f442eb348f48867d85f4ef2eaea",
  //torna平台secret
  "secret": "~#ZS~!*2B3I01vbW0f9iKH,rzj-%Xv^Q",
  //torna平台地址，填写自己的私有化部署地址
  "openUrl": "http://localhost:7700/api",
  //测试项目接口环境
  "debugEnvName":"测试环境",
  //测试项目接口地址
  "debugEnvUrl":"http://localhost:8088"
}

由于smart-doc的Maven插件已经自带推送文档到Torna的功能，我们只需双击smart-doc:torna-rest按钮即可；
接下来在Torna中，我们就可以看到相关的接口文档了，非常方便！

总结

Torna对于Swagger来说正是这样一种工具。Torna的文档界面和调试功能明显比Swagger高大上多了，而且还增加了权限管理功能，文档的安全性大大增强，大家觉得不错的话可以尝试下它！

参考：

官方文档：http://torna.cn/
项目源码地址: https://github.com/macrozheng/mall-learning/tree/master/mall-tiny-torna

除了swagger，你还用过哪几个在线文档生成器

1、gitbook

2、knife4j

介绍

给swagger换上新皮肤

功能增强点

全局参数

忽略参数属性

3、yapi

4、apidoc

5、showdoc

6、smartdoc

简介

生成API文档

使用postman测试接口

7、Torna

简介

项目架构

运行部署

使用

Post Directory