Java开发SpringBoot集成接口文档实现示例

目录

• swagger vs smart-doc

• Swagger的代码侵入性比较强
• 原生swagger不支持接口的参数分组
• 简单罗列一下smart-doc的优点

• 引入依赖，版本选择最新版本
• 新建配置文件smart-doc.json
• 通过执行maven 命令生成对应的接口文档
• 访问接口文档

• 1. 开启调试
• 2. 通用响应体
• 3. 自定义Header
• 4. 参数分组
• 5. idea配置doc
• 6. 完整配置

<!--引入smart-doc-->
<plugin>
  <groupId>com.github.shalousun</groupId>
  <artifactId>smart-doc-maven-plugin</artifactId>
  <version>2.2.7</version>
  <configuration>
    <configFile>./src/main/resources/smart-doc.json</configFile>
    <projectName>Smart-Doc初体验</projectName>
  </configuration>
</plugin>

{
  "outPath": "src/main/resources/static/doc"
}

//生成html
mvn -Dfile.encoding=UTF-8 smart-doc:html

{
  "serverUrl": "http://localhost:8080",      -- 服务器地址
  "allInOne": true,                -- 是否将文档合并到一个文件中，一般推荐为true
  "outPath": "src/main/resources/static/doc",  -- 指定文档的输出路径
  "createDebugPage": true,           -- 开启测试
  "allInOneDocFileName":"index.html",      -- 自定义文档名称
  "projectName": "初识smart-doc"        -- 项目名称
}

@Configuration
public class WebMvcAutoConfig implements WebMvcConfigurer {
    @Bean
    public CorsFilter corsFilter() {
        final UrlBasedCorsConfigurationSource urlBasedCorsConfigurationSource = new UrlBasedCorsConfigurationSource();
        final CorsConfiguration corsConfiguration = new CorsConfiguration();
        /* 是否允许请求带有验证信息 */
        corsConfiguration.setAllowCredentials(true);
        /* 允许访问的客户端域名 */
        corsConfiguration.addAllowedOrigin("*");
        /* 允许服务端访问的客户端请求头 */
        corsConfiguration.addAllowedHeader("*");
        /* 允许访问的方法名,GET POST等 */
        corsConfiguration.addAllowedMethod("*");
        urlBasedCorsConfigurationSource.registerCorsConfiguration("/**", corsConfiguration);
        return new CorsFilter(urlBasedCorsConfigurationSource);
    }
}

{
  "responseBodyAdvice":{            -- 通用响应体
    "className":"com.jianzh5.blog.base.ResultData"
  }
}

"requestHeaders": [ //设置请求头，没有需求可以不设置
    {
      "name": "token",//请求头名称
      "type": "string",//请求头类型
      "desc": "自定义请求头 - token",//请求头描述信息
      "value":"123456",//不设置默认null
      "required": false,//是否必须
      "since": "-",//什么版本添加的改请求头
      "pathPatterns": "/smart/say",//只有以/smart/say 开头的url才会有此请求头
      "excludePathPatterns":"/smart/add,/smart/edit" // url=/app/page/将不会有该请求头
    }
]

{
  "serverUrl": "http://localhost:8080",
  "allInOne": true,
  "outPath": "src/main/resources/static/doc",
  "createDebugPage": true,
  "allInOneDocFileName":"index.html",
  "projectName": "初识smart-doc",
  "packageFilters": "com.jianzh5.blog.smartdoc.*",
  "errorCodeDictionaries": [{
    "title": "title",
    "enumClassName": "com.jianzh5.blog.base.ReturnCode",
    "codeField": "code",
    "descField": "message"
  }],
  "responseBodyAdvice":{
    "className":"com.jianzh5.blog.base.ResultData"
  },
  "requestHeaders": [{
    "name": "token",
    "type": "string",
    "desc": "自定义请求头 - token",
    "value":"123456",
    "required": false,
    "since": "-",
    "pathPatterns": "/smart/say",
    "excludePathPatterns":"/smart/add,/smart/edit"
  }]
}