springboot项目中swagger2以及swagger2markup的用法

1.引入依赖
  pom.xml中需要两个依赖
  <1>启动swagger2的方式之一，用于启动swagger2的依赖，需要配合配置文件使用（另一种方式是引入springfox依赖，用配置类进行配置）
  
  <!--swagger2-->
  <dependency>
      <groupId>com.spring4all</groupId>
      <artifactId>swagger-spring-boot-starter</artifactId>
      <version>1.7.1.RELEASE</version>
  </dependency>

  <2>swagger2markup依赖，可将swagger2的API文档导出，在测试类中进行相关配置
  
  <!--swagger2markup-->
  <dependency>
      <groupId>io.github.swagger2markup</groupId>
      <artifactId>swagger2markup</artifactId>
      <version>1.3.1</version>
  </dependency>

2.启动swagger2

    在入口函数上添加 @EnableSwagger2Doc 注解 ，启动主程序，访问http://localhost:8080/swagger-ui.html 即可进入swagger2页面

3.使用swagger2markup导出本地文档

    在Spring测试类中添加对应方法，在测试类注解 @SpringbootTest 后添加(webEnvironment = SpringBootTest.WebEnvironment.DEFINED_PORT)，可以在不启动swagger2的情况下运行markup（实际是替你启动，生成文档后再自动关闭）

@Test
public void generateDocs() throws Exception {
    
    Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
            .withMarkupLanguage(MarkupLanguage.MARKDOWN)  
            // 输出Markdown格式，可以修改文档类型，例MarkupLanguage.ASCIIDOC
            .build();

    Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs"))
            .withConfig(config)
            .build()
            .toFolder(Paths.get("src/docs/markdown/generated")); 
            //这是生成的文档位置，可以修改为输出单文件，toFolder改为toFile
}

4.实际使用

<1>Controller中

  实际使用中，需要我们在Controller中的每一个方法上添加注解，已达到自动生成接口文档的作用  例：

@RequestMapping(value = "/testHaveParms",method = RequestMethod.POST)
@ApiOperation(notes = "返回用户名", value = "返回用户名")
@ApiImplicitParams({
        @ApiImplicitParam(value = "用户id", name = "id", dataType = "int", required = false),
        @ApiImplicitParam(value = "用户姓名", name = "name", dataType = "string", required = true)
})
public String test(int id,String name){
    return "用户名:"+name;
}

 @RequestMapping必须指定请求方法，不然API文档会重复出现此条接口

 @ApiOperation中添加接口名value和接口描述notes，如果不加参数@ApiOperation（“123”）则为接口名

 @ApiImplicitParams是由多个@ApiImplicitParam组成，用于多参数接口的参数描述，value为参数描述，name为参数名，dataType为数据类型（默认String），required为是否必填，如果没有特殊需要不需要@ApiImplicitParam

<2>配置文件中

1.swagger.base-package=com.example //包扫描路径，如果不写则默认全扫描，但是会出现error接口

2.swagger.global-operation-parameters[0] //增加全局参数

例如token:
swagger.global-operation-parameters[0].name=access_token
swagger.global-operation-parameters[0].description=user access token
swagger.global-operation-parameters[0].modelRef=string
swagger.global-operation-parameters[0].parameterType=header
swagger.global-operation-parameters[0].required=true

3.项目中如果继承了WebMvcConfigurationSupport，则在yml中配置的相关内容会失效， 需要重新指定静态资源，否则swagger2的页面路径找不到。

需要在Web配置类重写addResourceHandlers方法，如下

@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
    registry.addResourceHandler("/**").addResourceLocations(
            "classpath:/static/");
    registry.addResourceHandler("swagger-ui.html").addResourceLocations(
            "classpath:/META-INF/resources/");
    registry.addResourceHandler("/webjars/**").addResourceLocations(
            "classpath:/META-INF/resources/webjars/");
    super.addResourceHandlers(registry);
}

4.如果有拦截器，需要在重写addInterceptors方法时排除swagger2相关请求，不然会被拦截，如下

.excludePathPatterns("/swagger-resources/**", "/webjars/**", "/v2/**", "/swagger-ui.html/**");

<3>