附demo下载链接:
https://download.csdn.net/download/qq_43560721/12608814
相关注解总结:
1.@Api注解可以用来标记当前Controller的功能。
2.@ApiOperation注解用来标记一个方法的作用。
3.@ApiResponses:用在controller的方法上,用于表示一组响应;@ApiResponse:用在 @ApiResponses里边,一般用于表达一个错误的响应信息
4.@Configuration标注在类上,相当于把该类作为spring的xml配置文件中的,作用为:配置spring容器(应用上下文)。用@Bean标注方法等价于XML中配置bean。
5.@EnableSwagger2的作用是启用Swagger2相关功能。
6.@ApiImplicitParam注解用来描述一个参数,可以配置参数的中文含义,也可以给参数设置默认值,这样在接口测试的时候可以避免手动输入。
@ApiParam和@ApiImplicitParam的功能是相同的,但是@ApiImplicitParam的适用范围更广。
如果有多个参数,则需要使用多个@ApiImplicitParam注解来描述,多个@ApiImplicitParam注解需要放在一个@ApiImplicitParams注解中。
需要注意的是,@ApiImplicitParam注解中虽然可以指定参数是必填的,但是却不能代替@RequestParam(required = true),前者的必填只是在Swagger2框架内必填,抛弃了Swagger2,这个限制就没用了,所以假如开发者需要指定一个参数必填,@RequestParam(required = true)注解还是不能省略。
7.@ApiParam ,是注解api的参数,也就是用于swagger提供开发者文档,文档中生成的注释内容。
8.@RequestParam,是获取前端传递给后端的参数,可以是get方式,也可以是post方式。
9.@PathVariable,是获取get方式,url后面参数,进行参数绑定
10.如果参数是一个对象(例如上文的更新接口),对于参数的描述也可以放在实体类中,如下图
项目示例:
项目结构:
1.创建一个Spring Boot项目,添加依赖
贴出pom文件
<?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 http://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.1.7.RELEASE</version>
<relativePath/> <!-- lookup parent from repository -->
</parent>
<groupId>com.zly</groupId>
<artifactId>swagger</artifactId>
<version>0.0.1-SNAPSHOT</version>
<name>swagger</name>
<description>Demo project for Spring Boot</description>
<properties>
<java.version>1.8</java.version>
</properties>
<dependencies>
<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>
<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>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
<version>2.6.6</version>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
</project>
2.Swagger2配置
package cn.xxs.swagger.config;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Value;
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.service.ApiKey;
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 java.util.List;
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Value("${swagger.show}")
private boolean swaggerShow;
/**
* 指定文档扫描路径
* @return
*/
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
//是否开启 (true 开启 false隐藏。生产环境建议隐藏)
.enable(swaggerShow)
.pathMapping("/")
// 设置哪些接口暴露给Swagger展示
.select()
// 扫描所有有注解的api,用这种方式更灵活
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
//扫描的路径包,设置basePackage会将包下的所有被@Api标记类的所有方法作为api
.apis(RequestHandlerSelectors.basePackage("cn.xxs.swagger.controller"))
//指定路径处理PathSelectors.any()代表所有的路径
.paths(PathSelectors.any())
.build()
// 用来创建该API的基本信息,展示在文档的页面中(自定义展示的信息)
.apiInfo(apiInfo());
}
/**
* 文档基本信息
*
* @return
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
//设置文档标题(API名称)
.title("测试API")
//文档描述
.description("测试API接口,详细信息......")
//版本号
.version("1.1.0")
//联系信息
.contact(new Contact("xxs", "https://blog.csdn.net/qq_43560721", "1781195763@qq.com"))
.license("The Apache License")
.licenseUrl("http://www.baidu.com")
.build();
}
}
配置文件
swagger.show=true
3.映射配置类
package cn.xxs.swagger.config;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
/**
* 将jar包中的静态资源映射
*/
@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}
4.测试所需实体
package cn.xxs.swagger.pojo;
import io.swagger.annotations.ApiModelProperty;
public class User {
@ApiModelProperty(value = "用户姓名")
private String username;
@ApiModelProperty(value = "用户密码")
private String password;
public User(String username, String password) {
this.username = username;
this.password = password;
}
public User() {
}
public String getUsername() {
return username;
}
public void setUsername(String username) {
this.username = username;
}
public String getPassword() {
return password;
}
public void setPassword(String password) {
this.password = password;
}
}
5.书写测试接口
package cn.xxs.swagger.controller;
import cn.xxs.swagger.pojo.User;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.*;
import java.util.*;
@RestController
@Api(tags = "用户管理相关接口")
@RequestMapping("/user")
public class UserController {
/**
* 模拟数据库数据
*/
public static List<User> users = new ArrayList<>();
static {
users.add(new User("小四", "123"));
users.add(new User("小二", "456"));
}
/**
* 获取用户列表
* @return
*/
@GetMapping("/users")
@ApiOperation(value = "获取用户列表",notes = "获取所有用户的列表")
public Object users() {
Map<String, Object> map = new HashMap<>();
map.put("users", users);
return map;
}
/**
* 获取单个用户
* @param id
* @return
*/
@GetMapping("/{id}")
@ApiOperation(value = "获取单个用户",notes = "根据id查询某个用户的信息")
public User getUser(@ApiParam(name = "id", value = "用户的id",defaultValue = "1",required = true) @PathVariable Integer id){
return users.get(id);
}
/**
* 删除单个用户
* @param username
* @return
*/
@DeleteMapping("/delete")
@ApiOperation(value = "删除单个用户",notes = "根据username删除某个用户的信息")
public List<User> deleteUser(@ApiParam(name = "username", value = "用户名",defaultValue = "小四",required = true) @RequestParam String username){
Iterator<User> it = users.iterator();
while(it.hasNext()){
User x = it.next();
if(x.getUsername().equals(username)){
it.remove();
}
}
return users;
}
/**
* 添加用户
* @param username
* @param password
* @return
*/
@PutMapping("")
@ApiOperation(value = "添加用户",notes = "添加用户信息到用户列表")
public List<User> addUserInfo(@ApiParam(name = "username", value = "用户名",defaultValue = "李四",required = true) @RequestParam String username,
@ApiParam(name = "password", value = "用户密码",defaultValue = "123",required = true) @RequestParam String password){
users.add(new User(username, password));
return users;
}
/**
* 添加用户
* @param user
* @return
*/
@PutMapping("/add")
@ApiOperation(value = "添加用户",notes = "添加用户信息到用户列表")
public List<User> addUser(@RequestBody User user){
users.add(user);
return users;
}
/**
* 测试接口
* @param str
* @return
*/
@ApiResponses({
@ApiResponse(code = 200, message = "success"),
@ApiResponse(code = 10001, message = "参数不符合")
})
@PostMapping("/test")
@ApiOperation(value = "测试接口",notes = "根据指定字符串返回对应code")
public Integer test(@ApiParam(name = "str", value = "测试字符串",defaultValue = "1",required = true) @RequestParam String str){
int code = 10001;
switch (str){
case "1":
code = 200;
break;
default:
break;
}
return code;
}
}
5.启动类
package cn.xxs.swagger;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class SwaggerApplication {
public static void main(String[] args) {
SpringApplication.run(SwaggerApplication.class, args);
}
}
ok,运行后,访问
http://localhost:8080/swagger-ui.html
我们随便拉出一个接口测试一下:
另外我们可以在线调试,如下图所示: