2021-08-05

springboot + swagger
2018年08月08日 15:10:00
随着互联网技术的发展，现在的网站架构基本都由原来的后端渲染，变成了：前端渲染、先后端分离的形态，而且前端技术和后端技术在各自的道路上越走越远。
前端和后端的唯一联系，变成了API接口；API文档变成了前后端开发人员联系的纽带，变得越来越重要，swagger就是一款让你更好的书写API文档的框架。
书写API文档的工具有很多，但是能称之为“框架”的，估计也只有swagger了。
swagger的生态使用图：

红色部分为swagger官方推荐；

2．springBoot整合swagger示例：
代码参考ispms(项目管理)2018/7/30
2.1.pom.xml中新增依赖

	<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger2</artifactId>
	   <version>2.9.2</version>
	</dependency>
	<dependency>
   <groupId>io.springfox</groupId>
	   <artifactId>springfox-swagger-ui</artifactId>
	   <version>2.9.2</version>
	</dependency>

2.2.下载依赖（请用外网）
项目右击==>maven==>update Project 等待更新完成…

2.3.新增Swagger2.java
@Configuration
@EnableSwagger2
public class Swagger2 {
@Bean
public Docket createRestApi() {
ParameterBuilder tokenPar = new ParameterBuilder();
List pars = new ArrayList();
tokenPar.name(“Authorization”).description(“令牌”).modelRef(new ModelRef(“string”)).parameterType(“header”).required(false).build();
pars.add(tokenPar.build());
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage(“com.ctff.isbg.ispcm.flow.controller”))
.paths(PathSelectors.any())
.build()
.globalOperationParameters(pars);
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title(“xx网安项目管理 RESTful APIs”)
.description(“后台api接口文档”)
.version(“1.0”)
.build();
}

}
创建Swagger配置类时，类名随意创建；
但是类上面必须添加@Configuration、@EnableSwagger2这两个注解
（通过@Configuration注解，让Spring来加载该类配置，@EnableSwagger2注解来启用Swagger2。再通过被@Bean注解的函数创建Docket的Bean之后，apiInfo()用来创建该Api的基本信息（这些基本信息会展现在文档页面中）。）

select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现，本例采用指定扫描的包路径来定义，Swagger会扫描该包下所有Controller定义的API，并产生文档内容（除了被@ApiIgnore注解的API）。

这里如果函数上面不配置@Bean，那么Swagger只是启动了，没有创建API信息。
从上面配置类中可以创建多个函数并用@Bean注解，这样就可以针对不同的Controller创建出各自的API文档。
需要注意的是：在创建多个API时，需要指定API文档的名称。groupName()，如果不指定在项目启动的时候就会报错。

2.4.自定义静态资源映射
在SpringBoot集成Swagger的时候，我们需要增加swagger-ui.html映射到classpath:/META-INF/resources/，我们自定义配置类，继承WebMvcConfigurerAdapter，然后重写addResourceHandlers方法：
注意：在该启动类上加上@EnableWebMvc注解
想要启用MVC Java config，只需要将@EnableWebMvc添加到你的一个@Configuration class即可。
（参考：项目管理中在WebMvcConfig.java新增方法：addResourceHandlers）
/* 增加资源文件*/
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
//增加swagger资源registry.addResourceHandler("/js/").addResourceLocations(“classpath:/js/”);
registry.addResourceHandler(“swagger-ui.html”) .addResourceLocations(“classpath:/META-INF/resources/”);
registry.addResourceHandler("/webjars/").addResourceLocations(
“classpath:/META-INF/resources/webjars/”);
}

不加会导致资源映射问题。
我们在访问http://127.0.0.1:8188/swagger-ui.html 时，这个swagger-ui.html相关的所有前端静态文件都在springfox-swagger-ui-2.6.1.jar里面。
Spring Boot自动配置本身不会自动把/swagger-ui.html这个路径映射到对应的目录META-INF/resources/下面。我们加上以上代码去映射即可。
2.5.使用注解
在controller上加一些注解即可生成api文档
常用注解：
2.5.1.@api：用在类上，说明该类的作用

2.5.2.@ApiOperation：用在方法上，说明方法的作用

2.5.3.@ApiImplicitParams：用在方法上包含一组参数说明
2.5.4.@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面

注：@ApiImplicitParam注解可配的常用参数：
paramType：参数放在哪个地方
header请求参数的获取：@RequestHeader
query请求参数的获取：@RequestParam
path（用于restful接口）–>请求参数的获取：@PathVariable
name：参数名
dataType：参数类型
required：参数是否必须传
value：参数的意思
defaultValue：参数的默认值
…
具体其他注解及详细解释查看：
https://github.com/swagger-api/swagger-core/wiki/Annotations#apimodel

2.6.访问AIP接口文档
页面启动没报错了，访问http://127.0.0.1:8888/swagger-ui.html即可展示出页面

前端人员查看API图解：

详情参考文章：https://blog.csdn.net/tenghu8888/article/details/78734191

谢谢观看：如有说明不当的地方烦请指出，谢谢！^#