Swagger优势:给我们提供了一个全新的维护API文档的方式
一、创建springboot工程
可以通过Spring Initializr页面生成一个空的Spring Boot项目,当然也可以下载springboot-pom.xml文件,然后使用Maven构建一个Spring Boot项目。项目创建完成后,为了方便后面代码的编写您可以将其导入到您喜欢的IDE中,使用工具Intelli IDEA打开
二、依赖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 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.3.RELEASE</version>
<relativePath/> <!-- lookup parent from repository -->
</parent>
<groupId>com.xiaolonghong</groupId>
<artifactId>Swaggerdemo</artifactId>
<version>1.0-SNAPSHOT</version>
<name>Swaggerdemo</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.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
</project>
三、编写接口
1.创建三个包:cn.xiaolonghong.sbswagger.controller、cn.xiaolonghong.sbswagger.testcontroller、cn.xiaolonghong.sbswagger.model
2.在controller新建UserController.java类,testcontroller包下新建TestController.java类,在model包新建User.java类
UserController.java
注明L:提供用户的增、删、查、改、四个接口
package cn.xiaolonghong.sbswagger.controller;
import cn.xiaolonghong.sbswagger.model.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;
import springfox.documentation.annotations.ApiIgnore;
/**
1. 浏览器访问swagger-ui效果: http://localhost:8080/swagger-ui.html
2. 在Spring Boot项目中集成了Swagger2,启动项目后,
我们可以通过在浏览器中访问 http://localhost:8080/v2/api-docs 来验证,
你会发现返回的结果是一段JSON串,可读性非常差。
@ApiIgnore: Swagger文档不会显示拥有该注解的接口。
@ApiImplicitParams: 用于描述接口的非对象参数集。
@ApiImplicitParam: 用于描述接口的非对象参数,一般与@ApiImplicitParams组合使用。
@ApiOperation: 可设置对接口的描述。
注解属性 类型 描述
value String 接口说明。
notes String 接口发布说明。
tags Stirng[] 标签。
response Class<?> 接口返回类型。
httpMethod String 接口请求方式。
注解属性 描述
paramType 查询参数类型,实际上就是参数放在那里。取值: path:以地址的形式提交数据,根据id查询用户的接口就是这种形式传参。 query:Query string的方式传参。 header:以流的形式提交。 form:以Form表单的形式提交。
dataType 参数的数据类型。取值:Long,String
name 参数名字。
value 参数意义的描述。
required 是否必填。取值:true:必填参数,false:非必填参数。
注明:springboot-集成swagger教程及配置: https://itweknow.cn/blog-site/posts/2111459879.html
*/
@RestController
@RequestMapping("/user")
@Api(tags = "用户相关接口", description = "提供用户相关的Rest API")
public class UserController {
@ApiOperation("更新用户信息接口")
@PutMapping("/update")
public boolean update(@RequestBody User user) {
return true;
}
@ApiOperation("删除用户接口")
@DeleteMapping("/delete/{id}")
@ApiIgnore
public boolean delete(@PathVariable("id") int id) {
return true;
}
@ApiOperation("新增用户接口")
@PostMapping("add")
public boolean addUser(@RequestBody User user){
return false;
}
@ApiOperation("通过id查找用户接口")
@GetMapping("/find/{id}")
public User findById(@PathVariable("id") int id) {
return new User();
}
}
TestController.java
注明:提供一个测试接口
package cn.xiaolonghong.sbswagger.testcontroller;
import io.swagger.annotations.Api;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
/**
* 提供一个测试接口
*/
@RestController
@RequestMapping("test")
@Api(tags = "测试相关接口", description = "提供测试相关的Rest API")
public class TestController {
@GetMapping("/test")
public void test(){
System.out.println("test");
}
}
User.java
package cn.xiaolonghong.sbswagger.model;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
/*
接口相关注解
@ApiModel: 可设置接口相关实体的描述。
@ApiModelProperty: 可设置实体属性的相关描述。
注解属性 类型 描述
value String 字段说明。
name String 重写字段名称。
dataType Stirng 重写字段类型。
required boolean 是否必填。
example Stirng 举例说明。
hidden boolean 是否在文档中隐藏该字段。
allowEmptyValue boolean 是否允许为空。
allowableValues String 该字段允许的值,当我们API的某个参数为枚举类型时,使用这个属性就可以清楚地告诉API使用者该参数所能允许传入的值。
*/
@ApiModel("用户实体")
public class User {
/**
* 用户Id
*/
@ApiModelProperty("用户id")
private int id;
/**
* 用户名
*/
@ApiModelProperty("用户姓名")
private String name;
/**
* 用户地址
*/
@ApiModelProperty("用户地址")
private String address;
public int getId() {
return id;
}
public User setId(int id) {
this.id = id;
return this;
}
public String getName() {
return name;
}
public User setName(String name) {
this.name = name;
return this;
}
public String getAddress() {
return address;
}
public User setAddress(String address) {
this.address = address;
return this;
}
}
四、自定义响应信息
在config包下新建SwaggerConfig.java
package cn.xiaolonghong.sbswagger.config;
import com.google.common.base.Predicates;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.bind.annotation.RequestMethod;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.builders.ResponseMessageBuilder;
import springfox.documentation.schema.ModelRef;
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;
import java.util.Collections;
import static com.google.common.collect.Lists.newArrayList;
/**
* @Configuration 告诉Spring Boot需要加载这个配置类
* @EnableSwagger2 启用Swagger2,如果没加的话自然而然也就看不到后面的验证效果
*/
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.basePackage("cn.xiaolonghong.sbswagger.controller"))
.paths(Predicates.or(PathSelectors.ant("/user/add"),
PathSelectors.ant("/user/find/*")))
.build()
.apiInfo(apiInfo())
.useDefaultResponseMessages(false)
.globalResponseMessage(RequestMethod.GET, newArrayList(
new ResponseMessageBuilder()
.code(500)
.message("服务器发生异常")
.responseModel(new ModelRef("Error"))
.build(),
new ResponseMessageBuilder()
.code(403)
.message("资源不可用")
.build()
));
}
private ApiInfo apiInfo() {
return new ApiInfo(
"Spring Boot项目集成Swagger实例文档",
"我的CSDN博客网站:https://blog.csdn.net/qq_41086359,欢迎大家访问。",
"API V1.0",
"Luyi of service",
new Contact("lIUYI", "https://blog.csdn.net/qq_41086359", "amixiao@qq.com"),
"Apache", "http://www.apache.org/", Collections.emptyList());
}
}
五、编写一个启动类
App.java
package cn.xiaolonghong.sbswagger;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class App {
public static void main(String[] args) {
SpringApplication.run(App.class, args);
}
}
六、浏览器访问
1. 浏览器访问swagger-ui效果: http://localhost:8080/swagger-ui.html 2. 在Spring Boot项目中集成了Swagger2,启动项目后, 我们可以通过在浏览器中访问 http://localhost:8080/v2/api-docs 来验证, 你会发现返回的结果是一段JSON串,可读性非常差。
效果图