无侵入式接口文档smartDoc

工具使用

特别说明：仅供笔记使用

1 导入依赖

        
            com.github.shalousun
            smart-doc
            1.9.8
            test
        

2 核心配置文件

    private String serverUrl;
    private boolean isStrict;
    private boolean allInOne;
    private String outPath;
    private List sourceCodePaths;
    private List requestHeaders;
    private boolean coverOld;
    private List customResponseFields;
    private List errorCodes;
    private String packageFilters;
    private List revisionLogs;
    private boolean md5EncryptedHtmlName;
    private DocLanguage language;
    private boolean adoc;
    private List dataDictionaries;
    private List errorCodeDictionaries;
    private List apiObjectReplacements;
    private List rpcApiDependencies;
    private List apiConstants;
    private String projectName;
    private boolean skipTransientField = true;
    private boolean showAuthor = true;
    private boolean requestFieldToUnderline;
    private boolean responseFieldToUnderline;
    private boolean sortByTitle;
    private Boolean showJavaType;
    private Boolean inlineEnum;
    private String rpcConsumerConfig;
    private int recursionLimit;
    private boolean requestExample;
    private boolean responseExample;
    private String allInOneDocFileName;
    private boolean paramsDataToTree;
    private List ignoreRequestParams;
    private boolean displayActualType;
    private ResponseBodyAdvice responseBodyAdvice;

• serverUrl（类型：String）
  项目地址，会自动添加在生成的Controller地址之前 --> config.setServerUrl("http://localhost:8080");

• isStrict（类型：boolean）
  是否开启严格检查 开启严格检查后 要求public method必须加注释 默认false --> config.setStrict(true);

• allInOne（类型：boolean）
  设置所有文档在一个文件，建议设置为true，不然一个类生成一个文件，文件过多。单独提供某个类的接口文档时，可以设置为false --> config.setAllInOne(true);

• outPath（类型：String 建议设置）
  生成的文档输出目录，个人习惯输出到项目的静态文件里面，启动项目时能够访问。

• sourceCodePaths
  源代码路径，一般默认是src/main/java。

  "sourceCodePaths": [
    {
      "path": "src/main/java",
      "desc": "测试"
    }
  ]

• requestHeaders
  设置请求头

  "requestHeaders": [
    {
      "name": "token",
      "type": "string",
      "desc": "存放于cookie的校验信息",
      "required": true,
      "since": "-"
    }
  ]

生成样式

• coverOld（类型：boolean）
  是否覆盖文件，一般都是true。

• customResponseFields（类型：）
  自定义一些特殊属性的响应值，当响应出现该字段时，同名字段会使用你设置的值。

  "customResponseFields": [
    {
      "name": "userName",
      "desc": "用户名33333",
      "value": "测试"
    }
  ],

image.png

• errorCodes
  错误代码说明，会在最后单独弄一个模块进行显示。

  "errorCodes": [
    {
      "value": "500",
      "type": "errorType",
      "desc": "服务器出错",
      "ordinal": 123,
      "name": "errorName"
    }
  ]

错误

• packageFilters（类型：String ）
  扫描指定包及其子包下面的Controller，例如设置为com.example.demo.controller，实际扫描的是com.example.demo.controller*.*，即与controller同级并以controller前缀的包及其子包（ps：扫描同级相同前缀这个是无意间发现的，但一般也不会将一个包直接作为另一个包的前缀。还有，不止是包，也可以设置具体的类）。多个包通过都好隔开。
  ->config.setPackageFilters("com.example.demo");

• revisionLogs（类型：对象，非必须）
  修改日志，只有setAllInOne设置为true时文档变更记录才生效。

  "revisionLogs": [
    {
      "version": "版本--1.0",
      "status": "状态--创建",
      "author": "作者--zyb",
      "revisionTime": "修正时间--2020/11/02",
      "remarks": "修正描述--描述"
    }
  ]

生成图片

• md5EncryptedHtmlName
  是否对Controller进行加密，只有为单个的Controller生成html时才能使用，即AllInOne为false。

• language
  语言设置。

• adoc

• dataDictionaries;
  数据字典配置

• errorCodeDictionaries;
  略

• apiObjectReplacements;
  略

• rpcApiDependencies;
  略

• projectName;
  项目名称

• skipTransientField = true;
  略

• showAuthor = true;
  略

• requestFieldToUnderline;
  略

• responseFieldToUnderline;
  略

• sortByTitle;
  略

• showJavaType;
  略

• inlineEnum;
  略

• rpcConsumerConfig;
  略

• recursionLimit;
  略

• requestExample;
  略

• responseExample;
  略

• allInOneDocFileName;
  略

• paramsDataToTree;
  略

• ignoreRequestParams;
  略

• displayActualType;
  略

• responseBodyAdvice;
  略

3 代码测试

    @Test
    public void testBuilderControllersApi() {
        ApiConfig config = new ApiConfig();
        config.setStrict(true);//严格模式
        config.setAllInOne(true);//true则将所有接口合并到一个
        //markdown中，错误码合并到最后

        config.setOutPath("d:\\md");//输出目录
        // @since 1.2,如果不配置该选项，则默认匹配全部的controller,
        // 如果需要配置有多个controller可以使用逗号隔开
        config.setPackageFilters("com.power.doc.controller.app");
        //默认是src/main/java,maven项目可以不写
        

        //设置项目错误码列表，设置自动生成错误列表
        List errorCodeList = new ArrayList<>();

        //不是必须
        config.setErrorCodes(errorCodeList);

        ApiDocBuilder.buildApiDoc(config);
    }

---

smart 插件

1 插件依赖

            
                com.github.shalousun
                smart-doc-maven-plugin
                1.0.4
                
                    
                    ./src/main/resources/smart-doc.json
                    
                    测试DEMO
                    
                    
                    
                    
                    
                    
                        
                            org.springframework.boot:spring-boot-starter-tomcat
                        
                        
                            org.springframework.boot:spring-boot-starter-jdbc
                        
                    
                
                
                    
                        
                        compile
                        
                            markdown
                        
                    
                
            

2 编写配置文件smart-doc.json

{
  "outPath": "E:\\IDEAPROJECT\\tunnel\\src\\main\\resources\\static\\doc",
  "allInOne": true,
  "customResponseFields": [
    {
      "name": "resultCode",
      "desc": "Response code",
      "value": "200"
    },
    {
      "name": "resultMsg",
      "desc": "错误信息",
      "value": null
    }
  ],
  "requestHeaders": [
    {
      "name": "token",
      "type": "string",
      "desc": "存放于cookie的校验信息",
      "required": true,
      "since": "-"
    }
  ]
}

3 执行插件，生成文件

生成html

配合smartdoc的javadoc注解

由于smartdoc是根据javadoc注解来生成接口文档的，所以需要了解javadoc常用注解的使用。当指定了扫描的包后，smart-doc只扫描使用@Controller（@RestController这种也行）修饰的类，只扫描@RequestMapping（@GetMapping类也可以）修饰的方法。

• @param：用于方法上，对方法参数进行说明，使用格式如下：

@param 参数名 参数的描述

• @author：用于类上，标名开发该类的作者，使用格式如下：

@author 作者名

• @return：用于方法上，对方法返回值的说明，与@link配合使用，@link用于指定返回值类型，使用格式如下：

@return {@link 类名}

• ignore：用于实体属性上，用于过滤请求时的实体参数的某个字段，设置后smart-doc将不会将该字段输出到参数列表中。需要注意的是，这种方式针对的是所有接口，即不能单独给接口设置忽略那些字段，所以接口尽量使用独立的参数接收数据。

• required：用于实体属性上，设置了该属性在smart-doc输出参数列表是会显示为true。

/**
* 接口描述
*
* @param 参数名 参数的描述
* @return {@link User}
*/

• description：用于方法上，主要用于描述接口作用，描述内容不会输出在smart-doc接口文档上。

    /**
     * 获取列表-分页
     * @description 描述内容，不会出现在文档上
     *
     */

注意：导入了smartDoc插件后使用maven的install会出现如下错误：

Failed to execute goal org.apache.maven.plugins:maven-install-plugin:2.5.2:install (default-install) on project tunnel: Execution default-install of goal org.apache.maven.plugins:maven-install-plugin:2.5.2:install failed: Unable to load the mojo 'install' (or one of its required components) from the plugin 'org.apache.maven.plugins:maven-install-plugin:2.5.2'

错误由如下配置造成：

                
                
                    
                        
                        
                        compile
                        
                            html
                        
                    
                

错误记录：

1 java.lang.RuntimeException: ERROR: #HellowController() - bad @author javadoc from HellowController, must be add comment if you use it.

如提示，@author缺少注释，添加注释即可

添加注释