Springboot整个Swagger2,构建Api文档
手写Api文档的几个痛点:
1 文档需要更新的时候,需要再次发送一份给前端,也就是文档更新交流不及时。
2 接口返回结果不明确
3 不能直接在线测试接口,通常需要使用工具,比如postman
4 接口文档太多,不好管理
Swagger也就是为了解决这个问题,当然也不能说Swagger就一定是完美的,当然也有缺点,最明显的就是代码移入性比较强。
其他的不多说,想要了解Swagger的,可以去Swagger官网,可以直接使用Swagger editor编写接口文档,当然我们这里讲解的是SpringBoot整合Swagger2,直接生成接口文档的方式。
一 依赖
<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>
二 Swagger2配置类
package com.kyrie.mybatis.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;
/**
* @Author: txma
* @Date: 2019/3/31 21:50
* @Version: 1.0
*/
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket CreateRestApi(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.kyrie.mybatis.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Spring Boot中使用Swagger2构建RESTful API")
.description("restFul api 文档构建利器")
.termsOfServiceUrl("https://blog.csdn.net/m0_43584016")
.contact("txma")
.version("1.0")
.build();
}
}
三 Restful 接口
package com.kyrie.mybatis.controller;
import com.kyrie.mybatis.entity.Student;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;
import java.util.ArrayList;
import java.util.List;
/**
* @Author: txma
* @Date: 2019/3/31 22:06
* @Version: 1.0
*/
@RestController
@RequestMapping(value = "/student")
@Api(description = "学生管理")
public class StudentController {
private int flag;
ArrayList<Student> students = new ArrayList<>();
@ApiOperation(value = "获取学生列表", notes = "获取所有学生信息")
@RequestMapping(value = "/get", method = RequestMethod.GET)
public List<Student> hello() {
students.add(new Student("逻辑", "123456"));
students.add(new Student("叶文杰", "123456"));
for(Student attribute : students) {
System.out.println(attribute);
}
return students;
}
@ApiOperation(value = "新增学生",notes = "新增学生信息")
@RequestMapping(value = "/add",method = RequestMethod.POST)
public int addStudent(Student student){
return flag;
}
@ApiOperation(value = "获取学生详细信息",notes ="根据用户输入的id来查询学生的详细信息")
@ApiImplicitParam(name = "id",value = "学生id",required = true)
@RequestMapping(value = "user/{id}",method = RequestMethod.GET)
public Student getStudent(int id){
Student student = new Student(1,"kyrie","111111");
return student;
}
@ApiOperation(value = "删除学生信息",notes = "根据id删除学生信息")
@ApiImplicitParam(name = "id",value = "学生id",required = true)
@RequestMapping(value = "user{/id}",method = RequestMethod.DELETE)
public int delStudent(int id){
return 1;
}
}
四 项目结构
五 运行项目,访问https://locallhost:8080/swagger-ui.html,效果如下:
Description 描述参数名称,在controller中为参数添加描述,代码如下:
至此,springboot整合swagger2来构建Api文档已经完成
六 swagger常用注解说明
swagger通过注解表明该接口会生成文档,包括接口名、请求方法、参数、返回信息的等等。
@Api:修饰整个类,描述Controller的作用
@ApiOperation:描述一个类的一个方法,或者说一个接口
@ApiParam:单个参数描述
@ApiModel:用对象来接收参数
@ApiProperty:用对象接收参数时,描述对象的一个字段
@ApiResponse:HTTP响应其中1个描述
@ApiResponses:HTTP响应整体描述
@ApiIgnore:使用该注解忽略这个API
@ApiError :发生错误返回的信息
@ApiImplicitParam:一个请求参数
@ApiImplicitParams:多个请求参数