Swagger2 前后端接口插件
目录
一、Swagger2 接口文档插件
1.Swagger2的特点
- 可以在代码层面自动生成接口文档。
- 修改接口，接口文档也随之修改。
- 接口文档的ui界面体验比较好。
- 如果接口功能已完成开发，可以通过swagger进行接口的功能测试。
二、Swagger的使用
1.引入依赖
pom.xml
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>2.4.4</version>
<relativePath/> <!-- lookup parent from repository -->
</parent>
<groupId>com.qf</groupId>
<artifactId>swagger-boot-demo</artifactId>
<version>0.0.1-SNAPSHOT</version>
<name>swagger-boot-demo</name>
<description>Demo project for Spring Boot</description>
<properties>
<java.version>1.8</java.version>
<!--swagger-->
<swagger.version>2.9.2</swagger.version>
</properties>
<dependencies>
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
</dependency>
<!--swagger start-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>${swagger.version}</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>${swagger.version}</version>
</dependency>
<!--swagger end-->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-thymeleaf</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
</project>
2.向config文件中添加Swageer的配置类
/**
* Swagger基础配置类
* 此类相当于配置文件, 项目启动就立即自动加载此类
*
* @author
*/
@Configuration
@EnableSwagger2
public class SwaggerConfiguration {
@Bean
public Docket buildDocket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(buildApiInfo())
.select()
// 要扫描的API(Controller)基础包
.apis(RequestHandlerSelectors.basePackage("com.qf.swageer2.demo"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo buildApiInfo() {
Contact contact = new Contact("xxx项目","","");
return new ApiInfoBuilder()
.title("xxx项目API文档")
.description("平台管理服务api")
.contact(contact)
.version("1.0.0").build();
}
}
3.在启动类上打上注解@EnableSwagger2
@SpringBootApplication
@EnableSwagger2
public class SwaggerBootDemoApplication {
public static void main(String[] args) {
SpringApplication.run(SwaggerBootDemoApplication.class, args);
}
}
4.编写实体类User
package com.qf.swagger.boot.demo.entity;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import java.util.Date;
@Data
@ApiModel(value = "用户实体类",description = "请求的参数实体")
public class User {
@ApiModelProperty(value="用户的id",example = "1029292929211001")
private Long id;
@ApiModelProperty(value = "用户名称",example = "张三")
private String name;
@ApiModelProperty(value = "年龄", example = "25")
private Integer age;
@ApiModelProperty(value = "生日", example = "2021-11-04T13:46:56.711Z")
private Date birthday;
@ApiModelProperty(value = "性别", example = "男,女")
private String sex;
@ApiModelProperty(value = "是否婚配", example = "true, false")
private Boolean isMarry;
@ApiModelProperty(value = "描述信息")
private String desc;
}
5.编写接口，在接口中使用swagger注解
package com.qf.swagger.boot.demo.controller;
import com.qf.swagger.boot.demo.entity.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
@RequestMapping("/api/user")
@Api(value = "用户管理",tags = "UserController",description = "用户管理api")
public class UserController {
@ApiOperation("根据用户id查询用户信息")
@GetMapping("/select/{id}")
public User findUserById(@ApiParam("用户id") @PathVariable(value="id") Long id){
return null;
}
}
6.编写配置文件
server:
port: 9001
7.启动项目访问swagger接口文档
启动路径：
三、swagger中的常用注解：
@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类中的一个方法
@ApiParam：单个参数的描述信息
@ApiModel：用对象来接收参数
@ApiModelProperty：用对象接收参数时，描述对象的一个字段
