Swagger Restful API 文档在线自动生成框架
一、背景和简介
- 背景
前后端分离的时代背景下
- 后端团队开发
- 后端控制层,服务层,数据访问层
- 前端团队
- 前端控制层,视图层
前后端通过API交互,实现松耦合,相对独立
产生一个问题:
- 前后端集成联调,前端人员和后端人员无法做到"即时协商,尽早解决",最终可能导致问题集中爆发
解决方案:
- 指定scheme,实时更新后端提供的API接口,降低集成风险
- 简介
Swagger是世界上最流行的API框架,以Restful风格实时自动更新API接口文档。
二、与Springboot集成和使用
- 导入依赖
<!-- 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>
- 配置swagger config 初始化
import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.util.ArrayList;
import java.util.List;
/**
* Swagger配置初始化
*/
@Configuration
// 开启swagger2
@EnableSwagger2
public class Swagger2 {
//这里配置Docket Bean实例
}
- 配置Swagger接口实例
package com.comtom.pms.config;
import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.util.ArrayList;
import java.util.List;
/**
* Swagger配置Docket Bean实例
*/
@Configuration
@EnableSwagger2
public class Swagger2 {
@Bean
public Docket createRestApi() {
return new Docket( new DocumentationType("swagger","2.0"))
.apiInfo(apiInfo())
.select()
/*
* 扫描方式:
RequestHandlerSelectors配置扫描接口方式
basePackage("com.xxx.controller");指定要扫描的包
any();全部扫描
none();全不扫描
withClassAnnotation(RestController.class);扫描类上的注解,参数是一个注解的反射对象
withMethodAnnotation(ApiOperation.class);扫描方法上的注解
*/
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
.build();//构建设命令
}
//构建api描述信息
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("接口标题")
.description("接口描述")
.termsOfServiceUrl("团队连接")
.contact(new Contact("作者信息","null","作者邮箱"))
.version("版本号")
.build();//构建设命令
}
}
- 配置数据模型
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
@ApiModel
public class MaterielRequestEntity {
@ApiModelProperty(value = "编号", required = true)
private String code;
public String getCode() {
return code;
}
public void setCode(String code) {
this.code = code;
}
}
- 配置具体接口信息
import com.comtom.pms.service.ProductService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.*;
@Controller
@RequestMapping("/materiel")
@Api(tags = "标签名")
public class ProductController {
@Autowired
private ProductService productService;
@RequestMapping(method = RequestMethod.GET)
@ApiOperation("接口描述")
@ResponseBody
public String query(@RequestParam(value = "format", required = false) String format,
@RequestParam(value = "code", required = true) String code){
String re = productService.getList(code);
return re;
}
- 启动Springboot
- 使用场景:根据部署环境判断是否开启swagger-ui
方式一:
1、新建一个application-dev.properties,生产环境时的配置,设置端口号为8081
2、新建一个application-pro.properties,发布环境时的配置,设置端口号为8082
3、在application.properties中激活生产环境时的配置:
spring.profiles.active=pro
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
import org.springframework.web.bind.annotation.RequestMapping;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.util.ArrayList;
import static springfox.documentation.service.ApiInfo.DEFAULT_CONTACT;
@Configuration
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {
//配置了Swagger的Docket的bean实例
@Bean
public Docket docket(Environment environment){
//设置要显示的Swagger环境
Profiles profiles = Profiles.of("pro");
//通过environment.acceptsProfiles判断是否处在自己设定的环境当中
boolean flag = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.enable(flag)
.select()
.apis(RequestHandlerSelectors.basePackage("com.xxx.swagger.controller"))
.build();
}
}
方拾二:
使用注解 @Value()
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.ViewControllerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
* 开启在线接口文档和添加相关配置
*/
@Configuration
@EnableSwagger2
public class Swagger2Config extends WebMvcConfigurerAdapter {
@Value("${swagger.enable}")
private Boolean enable;
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.enable(enable)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.xxx.controller"))
.paths(PathSelectors.any())
//.paths(PathSelectors.none())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("接口文档")
.description("此系统为新架构Api说明文档")
.termsOfServiceUrl("")
.contact(new Contact("", "", ""))
.version("1.0")
.build();
}
/**
* swagger ui资源映射
* @param registry
*/
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
}
/**
* swagger-ui.html路径映射,浏览器中使用/api-docs访问
* @param registry
*/
@Override
public void addViewControllers(ViewControllerRegistry registry) {
registry.addRedirectViewController("/api-docs","/swagger-ui.html");
}
}
方式三:
使用注解@Profile({“dev”,“test”}) 表示在开发或测试环境开启,而在生产关闭。
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.ViewControllerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
* 主要用途:开启在线接口文档和添加相关配置
*/
@Configuration
@EnableSwagger2
@Profile({“dev”,“test”})
public class Swagger2Config extends WebMvcConfigurerAdapter {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.xxx.controller"))
.paths(PathSelectors.any())
//.paths(PathSelectors.none())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("auth系统数据接口文档")
.description("此系统为新架构Api说明文档")
.termsOfServiceUrl("")
.contact(new Contact("", "", ""))
.version("1.0")
.build();
}
/**
* swagger ui资源映射
* @param registry
*/
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
}
/**
* swagger-ui.html路径映射,浏览器中使用/api-docs访问
* @param registry
*/
@Override
public void addViewControllers(ViewControllerRegistry registry) {
registry.addRedirectViewController("/api-docs","/swagger-ui.html");
}
}
方式四:
使用注解@ConditionalOnProperty(name = “swagger.enable”, havingValue = “true”) 然后在测试配置或者开发配置中 添加 swagger.enable = true 即可开启,生产环境不填则默认关闭Swagger
#Swagger lock
swagger:
enabled: true
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.ViewControllerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
* 主要用途:开启在线接口文档和添加相关配置
*/
@Configuration
@EnableSwagger2
@ConditionalOnProperty(name ="enabled" ,prefix = "swagger",havingValue = "true",matchIfMissing = true)
public class Swagger2Config extends WebMvcConfigurerAdapter {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.xx.controller"))
.paths(PathSelectors.any())
//.paths(PathSelectors.none())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("auth系统数据接口文档")
.description("此系统为新架构Api说明文档")
.termsOfServiceUrl("")
.contact(new Contact("", "", ""))
.version("1.0")
.build();
}
/**
* swagger ui资源映射
* @param registry
*/
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
}
/**
* swagger-ui.html路径映射,浏览器中使用/api-docs访问
* @param registry
*/
@Override
public void addViewControllers(ViewControllerRegistry registry) {
registry.addRedirectViewController("/api-docs","/swagger-ui.html");
}
}