目录
一、背景
前后端分离时,后端人员往往是要自己独立开发出一个能使用的接口,此时,类似于postman、Swagger、idea插件等等这些api工具就用的上了。当然这篇文章主要介绍Swagger搭建和使用。
环境:SpringBoot + Swagger2
二、Swagger使用介绍
1、控制器--Controller中使用Swagger
属性 | 说明 |
@Api(tags = "xx管理") | 修饰类上,tags标注此类的作用 |
@ApiOperation(notes="xx", value="xx") | 修饰方法上,notes标准方法说明,value标准方法具体作用(增删改查) |
@ApiResponse(code=xx, message="xx") | 修饰方法上,code响应成功的状态码,message是成功信息 |
2、DTO传输层Swagger用法
属性 | 说明 |
@ApiModelProperty(name="xx", value="xx") | 修饰属性,属性说明,name对象属性名称,value对应属性说明 |
@NotNull(message="xxx不能为空") | 修饰属性,表明属性是非空的,必输 |
@Length(max=xx) | 修饰属性,一般为字符,表示最大长度限制 |
例子说明
WordController.java
package com.essm.controller;
import com.essm.entity.WordDO;
import com.essm.remote.WordReqDTO;
import com.essm.remote.WordRspDTO;
import com.essm.service.WordService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiResponse;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;
import java.util.List;
/**
* 单词控制层
*
* @author :HUANG ZHI XUE
* @date :Create in 2020-08-18
*/
@RestController
@Api(tags = "单词管理")
public class WordController {
@Autowired
WordService wordService;
@ApiOperation(notes = "单词管理", value = "单词管理-查询接口")
@ApiResponse(code = 200, message = "查询成功")
@PostMapping("/listWordInfo")
public List<WordRspDTO> listWordInfo(@Validated @RequestBody WordReqDTO reqDto) {
return wordService.listWordInfo(reqDto);
}
}
WordReqDTO.java
package com.essm.remote;
import io.swagger.annotations.ApiModelProperty;
import javax.validation.constraints.NotNull;
/**
* 请求通用dto
*
* @author :HUANG ZHI XUE
* @date :Create in 2020-08-18
*/
public class WordReqDTO {
/** 单词编号 */
@ApiModelProperty(name = "id", value = "单词编号", required = true)
@NotNull(message = "单词编号不能为空")
private Integer id;
/** 用户编号 */
private Integer trl;
/** 单词中文 */
private String chinese;
/** 单词英文 */
private String english;
/** 单词状态位 */
private Integer sign;
public WordReqDTO() {
}
public WordReqDTO(Integer id, Integer trl, String chinese, String english, Integer sign) {
this.id = id;
this.trl = trl;
this.chinese = chinese;
this.english = english;
this.sign = sign;
}
public Integer getId() {
return id;
}
public void setId(Integer id) {
this.id = id;
}
public Integer getTrl() {
return trl;
}
public void setTrl(Integer trl) {
this.trl = trl;
}
public String getChinese() {
return chinese;
}
public void setChinese(String chinese) {
this.chinese = chinese;
}
public String getEnglish() {
return english;
}
public void setEnglish(String english) {
this.english = english;
}
public Integer getSign() {
return sign;
}
public void setSign(Integer sign) {
this.sign = sign;
}
@Override
public String toString() {
return "WordDO{" +
"id=" + id +
", trl=" + trl +
", chinese='" + chinese + '\'' +
", english='" + english + '\'' +
", sign=" + sign +
'}';
}
}
三、Swagger环境搭建
1、pom.xml依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>
2、加入swagger配置文件SwaggerConfig.java
package com.essm.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
* Swagger配置
*
* @author :HUANG ZHI XUE
* @date :Create in 2020-08-13
*/
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createApi(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.essm.controller"))
.paths(PathSelectors.any())
.build();
}
//设置swagger的一些信息
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Swagger2")
.description("Restful API接口")
.version("1.0.1")
.build();
}
}
3、如果路径做了拦截,需要放行swagger页面(自己项目比较老,看实际情况加即可)
重心在
/**
* 添加静态资源文件,外部可以直接访问地址
*
* @param registry
*/
public void addResourceHandlers(ResourceHandlerRegistry registry) {
//解决静态资源无法访问
registry.addResourceHandler("/static/**")
.addResourceLocations("classpath:/static/");
// 解决swagger无法访问
registry.addResourceHandler("/swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");
// 解决swagger的js文件无法访问
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
}
配置类全:
package com.essm.config;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.ViewControllerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import java.io.IOException;
/**
* @Description
* 扩展SpringMVC功能
* 1、固定页面跳转
* 2、拦截器
* @Author xuexue
* @Date 2020/5/19 19:52
*/
@Configuration
public class EssmMvcConfig implements WebMvcConfigurer {
@Autowired
private StaticPagePathFinder staticPagePathFinder;
public void addViewControllers(ViewControllerRegistry registry) {
registry.addViewController("/essm.html").setViewName("index");
registry.addViewController("/essm").setViewName("index");
//addViewControllers可以方便的实现一个请求直接映射成视图,而无需书写controller
//registry.addViewController(
// "请求路径").setViewName("请求页面文件路径")
try{
for(StaticPagePathFinder.PagePaths pagePaths :staticPagePathFinder.findPath()){
String urlPath = pagePaths.getUrlPath();
registry.addViewController(urlPath+".html").setViewName(pagePaths.getFilePath());
if(!urlPath.isEmpty()) {
registry.addViewController(urlPath).setViewName(pagePaths.getFilePath());
}
}
}catch(IOException e){
throw new RuntimeException("Unable to locate static pages:"+e.getMessage(),e);
}
}
/**
* 登录拦截器
*
* @param registry
*/
public void addInterceptors(InterceptorRegistry registry) {
String[] excludes = new String[]{"/login.html", "/login", "/essm", "/header.html", "/essm.html", "/static/**"};
registry.addInterceptor(new MyInterceptor()).
addPathPatterns("/**").
excludePathPatterns(excludes);
}
/**
* 添加静态资源文件,外部可以直接访问地址
*
* @param registry
*/
public void addResourceHandlers(ResourceHandlerRegistry registry) {
//解决静态资源无法访问
registry.addResourceHandler("/static/**")
.addResourceLocations("classpath:/static/");
// 解决swagger无法访问
registry.addResourceHandler("/swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");
// 解决swagger的js文件无法访问
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}
4、对应扫描包下建立一个WordController
5、启动项目,项目地址加/swagger-ui.html访问,如图