工具使用

特别说明：仅供笔记使用

1 导入依赖

        <dependency>
            <groupId>com.github.shalousun</groupId>
            <artifactId>smart-doc</artifactId>
            <version>1.9.8</version>
            <scope>test</scope>
        </dependency>

2 核心配置文件

    private String serverUrl;
    private boolean isStrict;
    private boolean allInOne;
    private String outPath;
    private List<SourceCodePath> sourceCodePaths;
    private List<ApiReqHeader> requestHeaders;
    private boolean coverOld;
    private List<CustomRespField> customResponseFields;
    private List<ApiErrorCode> errorCodes;
    private String packageFilters;
    private List<RevisionLog> revisionLogs;
    private boolean md5EncryptedHtmlName;
    private DocLanguage language;
    private boolean adoc;
    private List<ApiDataDictionary> dataDictionaries;
    private List<ApiErrorCodeDictionary> errorCodeDictionaries;
    private List<ApiObjectReplacement> apiObjectReplacements;
    private List<RpcApiDependency> rpcApiDependencies;
    private List<ApiConstant> 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<String> 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<ApiErrorCode> errorCodeList = new ArrayList<>();

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

        ApiDocBuilder.buildApiDoc(config);
    }

smart 插件

1 插件依赖

            <plugin>
                <groupId>com.github.shalousun</groupId>
                <artifactId>smart-doc-maven-plugin</artifactId>
                <version>1.0.4</version>
                <configuration>
                    <!--指定生成文档的使用的配置文件,配置文件放在自己的项目中-->
                    <configFile>./src/main/resources/smart-doc.json</configFile>
                    <!--指定项目名称-->
                    <projectName>测试DEMO</projectName>
                    <!--smart-doc实现自动分析依赖树加载第三方依赖的源码，如果一些框架依赖库加载不到导致报错，这时请使用excludes排除掉-->
                    <!--                    <excludes>-->
                    <!--                        &lt;!&ndash;格式为：groupId:artifactId;参考如下&ndash;&gt;-->
                    <!--                        <exclude>com.alibaba:fastjson</exclude>-->
                    <!--                    </excludes>-->
                    <excludes>
                        <exclude>
                            org.springframework.boot:spring-boot-starter-tomcat
                        </exclude>
                        <exclude>
                            org.springframework.boot:spring-boot-starter-jdbc
                        </exclude>
                    </excludes>
                </configuration>
                <executions>
                    <execution>
                        <!--如果不需要在执行编译时启动smart-doc，则将phase注释掉-->
                        <phase>compile</phase>
                        <goals>
                            <goal>markdown</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>

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'

错误由如下配置造成：

                <!--如果需要执行install,会报错，请将该配置注释掉-->
                <executions>
                    <execution>
                        <!--如果不需要在执行编译时启动smart-doc，则将phase注释掉-->
                        <!--phase与goals配合使用表示在编译期执行smart-doc的html-->
                        <phase>compile</phase>
                        <goals>
                            <goal>html</goal>
                        </goals>
                    </execution>
                </executions>

错误记录：

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

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

添加注释

无侵入式接口文档smartDoc