文章目录
- 一、引入Swagger
- 1. 添加maven依赖
- 2. 启动swagger
- 3. 访问出现404问题解决
- 4. 详细一点的配制
- 二、配制接口信息
- 1. Controller里的配制
- 2. Bean里的配制
- 3. 项目中的效果
- 三、总结
一、引入Swagger
1. 添加maven依赖
<!--swagger依赖-->
<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. 启动swagger
添加一个最简单的配制类，即可访问swagger首页
SwaggerConfig.java
package com.sc.springboot.config;
@Configuration
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {
}只要在配制类中开启了swagger，就可以通过http://localhost:8080/swagger-ui.html访问swagger页面
3. 访问出现404问题解决
如果项目中出现了WebMvcConfigurationSupport配制类，那么application.yml文件中的配制的默认资源访问路径就会失效，所以要重写在新的配制类中，重写资源路径。
重写addResourceHandlers和configureDefaultServletHandling方法，按下列HeadConfig.java配制即可
HeadConfig.java
package com.sc.springboot.config;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.CorsRegistry;
import org.springframework.web.servlet.config.annotation.DefaultServletHandlerConfigurer;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
/**
* Controller跨域处理
*/
@Configuration
public class HeadConfig extends WebMvcConfigurationSupport {
@Override
public void addCorsMappings(CorsRegistry registry) {
registry.addMapping("/**")
.allowCredentials(true) //允许携带cookie
.maxAge(3600); //cookie有效时间,单位：秒
}
/*
* 重新指定资源位置
* */
@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);
}
/**
* 配置servlet处理
*/
@Override
public void configureDefaultServletHandling(DefaultServletHandlerConfigurer configurer) {
configurer.enable();
}
}4. 详细一点的配制
（1）SwaggerConfig.java
package com.sc.springboot.config;
@Configuration
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {
/*
* 一个Docket Bean对应一个分组，可添加多个分组
*/
@Bean
public Docket docket1(Environment environment){
/*
*测试环境可用，这个主要是用来读取当前的运行环境的，
*只有在开发环境中才启用api文档
*/
Profiles profiles = Profiles.of("dev","test");
//通过environment.accptsProfiles判断是否处在自己设定的环境当中
boolean flag = environment.acceptsProfiles(profiles);
//添加全局配制，所有的请求都要带上请求头参数
ParameterBuilder token = new ParameterBuilder();
List<Parameter> pars = new ArrayList<Parameter>();
token.name("token").description("user token")
.modelRef(new ModelRef("string")).parameterType("header")
.required(false).build();
pars.add(token.build());
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.groupName("默认分组")
//根据当前的运行环境决定是否启用swagger
.enable(flag)
.select()
//apis可以配置该分组要扫描哪些Controller
.apis(RequestHandlerSelectors.basePackage("com.sc.springboot.controller"))
//paths配制过滤路径，可以选择在该组中，显示哪个路径的api
.paths(PathSelectors.any())
.build();
//添加此用户的一些全局配制,这里给所有接口都添加token_id请求头参数
.globalOperationParameters(pars);
}
//配制Swagger信息=apiInfo()，这是一些界面信息
private ApiInfo apiInfo(){
Contact DEFAULT_CONTACT = new Contact("", "", "");
return new ApiInfo("Demo平台后端接口",
"Demo平台API",
"v1.0",
"",
DEFAULT_CONTACT,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList<VendorExtension>());
}
}具体可以更改哪些信息，可以直接查看swagger的配制源码
（2）切换生产环境的方式
在application-dev.yml和application-pro.yml中放主要信息
application.yml中指定开发环境
spring:
profiles:
active: dev # 指定开发环境二、配制接口信息
1. Controller里的配制
这里主要是给每一个接口添加请求参数和返回参数
@Api(tags = "登录管理") //对这个controller进行注释
@Controller
@ResponseBody
public class LoginController {
@ApiOperation("用户注销登录") //对接口进行描述
@ApiImplicitParams({ //添加请求参数，可添加多个，paramType是请求的参数位置
@ApiImplicitParam(name = "token", value = "token信息",paramType = "header")
})
@ApiResponses({ //添加返回信息，可返回多个，对应不同的状态吗
@ApiResponse(code = 200, message = "注销成功"),
@ApiResponse(code = 401, message = "请登录后操作")
})
@GetMapping("sc/logout")
public User logout(HttpServletRequest request){
}
@ApiOperation(value = "用户登录")
@ApiImplicitParams({
@ApiImplicitParam(name = "userName", value = "用户名"),
@ApiImplicitParam(name = "password", value = "密码")
})
@ApiResponses({
@ApiResponse(code=200,message = "登录成功"),
@ApiResponse(code=402,message = "用户名或密码错误"),
})
@PostMapping("login")
public User login(@RequestParam String userName,@RequestParam String password, HttpServletResponse response){
}
}2. Bean里的配制
对Controller中的参数进行说明后，有的值由于是对象类型的，为了给对象里的属性添加描述，我们需要在Bean类里添加相应的注解
package com.sc.springboot.bean;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
//给这个实体类添加注释，用@ApiModel
@ApiModel(value = "用户信息信息")
public class User{
//给字段添加描述用@ApiModelProperty
@ApiModelProperty(value = "用户id", dataType = "String")
private String user_id;
@ApiModelProperty(value = "用户名称", dataType = "String")
private String user_name;
//省略get、set方法
}3. 项目中的效果
三、总结
最近项目比较多，都是采取前后端分离方式的，要编写大量的接口，之前我们团队都是利用word或YApi来写接口文档，每次更改都要重新编辑文档，修改版本号，实在是太麻烦了。今天突发奇想，为啥不自动生成文档接口呢，然后就捣鼓了一下，简单记录一下这个过程。
这个工具确实挺方便的，还可以在首页直接测试，postman都不需要了，不过也有很多坑，比如返回嵌套类型的json数据，下篇再具体说说。
本文章为转载内容，我们尊重原作者对文章享有的著作权。如有内容错误或侵权问题，欢迎原作者联系我们进行内容更正或删除文章。
