概述
前后端分离开发模式中,api 文档是最好的沟通方式。Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。具有及时性 (接口变更后,能够及时准确地通知相关前后端开发人员),规范性 (并且保证接口的规范性,如接口的地址,请求方式,参数及响应格式和错误信息),一致性 (接口信息一致,不会出现因开发人员拿到的文档版本不一致,而出现分歧),可测性 (直接在接口文档上进行测试,以方便理解业务) 的特点。
配置Swagger2
- 引入依赖
<!--swagger-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
</dependency>
- 写配置类,可以直接使用下面的配置
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
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 {
@Bean
public Docket webApiConfig(){
return new Docket(DocumentationType.SWAGGER_2)
.groupName("webApi")
.apiInfo(webApiInfo())
.select()
//只显示api路径下的页面
//.paths(Predicates.and(PathSelectors.regex("/api/.*")))
.build();
}
private ApiInfo webApiInfo(){
return new ApiInfoBuilder()
.title("网站-API文档")
.description("本文档描述了网站微服务接口定义")
.version("1.0")
.contact(new Contact("xg", "http://xg.com", "2218877219@qq.com"))
.build();
}
}
-
测试,启动Spring Boot主程序,访问:http://localhost:端口号/swagger-ui.html,端口号是自己项目设置的端口号。
Try it out–>Execute
-
测试结果:
-
Swagger 使用的常用注解及其说明:
@Api:用在类上,说明该类的作用。
@ApiOperation:用在方法上,给API增加方法说明。
@ApiParam,@ApiImplicitParams,@ApiImplicitParam:用在参数上,给API参数增加说明。
@ApiModel 和 @ApiModelProperty主要是作用到实体类上,当接口中有一个方法的返回值为该对象时,就会在文档的model中显示该类的信息
@ApiIgnore:用来排除不需要的接口信息
@Api(tags = "老师管理接口")
@RestController
@RequestMapping(value="/admin/teacher")
public class TeacherController {
@Autowired
private TeacherService teacherService;
//删除老师
@ApiOperation("逻辑删除老师")
@DeleteMapping("{id}")
public boolean removeById(@ApiParam(name = "id", value = "老师ID", required = true) @PathVariable String id){
return teacherService.removeById(id);
}
//查询所有老师列表
@ApiOperation("所有老师列表")
@GetMapping("findAll")
public List<Teacher> findAll(){
List<Teacher> list = teacherService.list();
return list;
}
}
- 补充说明:
如果项目中整合了Security,需要在其配置文件中将swagger的访问放行。
@Override
public void configure(WebSecurity web) throws Exception {
web.ignoring()
.antMatchers("/swagger-ui.html")
.antMatchers("/v2/**")
.antMatchers("/swagger-resources/**");
}