**
SpringBoot整合swagger
**
1、引入maven
<?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>
<modules>
<module>springboot-test</module>
<module>swagger</module>
</modules>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>2.4.5</version>
</parent>
<groupId>org.bc</groupId>
<artifactId>springboot-study</artifactId>
<version>1.0-SNAPSHOT</version>
<packaging>pom</packaging>
<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<maven.compiler.source>1.8</maven.compiler.source>
<maven.compiler.target>1.8</maven.compiler.target>
<jackson.version>2.10.0</jackson.version>
</properties>
<dependencies>
<dependency>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
<version>4.12</version>
<scope>test</scope>
</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>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
<version>${jackson.version}</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-core</artifactId>
<version>${jackson.version}</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-annotations</artifactId>
<version>${jackson.version}</version>
</dependency>
</dependencies>
<build>
<pluginManagement><!-- lock down plugins versions to avoid using Maven defaults (may be moved to parent pom) -->
<plugins>
<!-- clean lifecycle, see https://maven.apache.org/ref/current/maven-core/lifecycles.html#clean_Lifecycle -->
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<version>3.1.0</version>
</plugin>
</plugins>
</pluginManagement>
</build>
</project>
<?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">
<parent>
<artifactId>springboot-study</artifactId>
<groupId>org.bc</groupId>
<version>1.0-SNAPSHOT</version>
</parent>
<modelVersion>4.0.0</modelVersion>
<artifactId>swagger</artifactId>
<properties>
<maven.compiler.source>8</maven.compiler.source>
<maven.compiler.target>8</maven.compiler.target>
</properties>
<dependencies>
<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>
<dependency>
<groupId>commons-lang</groupId>
<artifactId>commons-lang</artifactId>
<version>2.6</version>
</dependency>
</dependencies>
2、编写配置类
package org.bc.swagger;
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;
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi(){
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.any()).paths(PathSelectors.any()).build();
}
private ApiInfo apiInfo(){
return new ApiInfoBuilder().build();
}
}
3、编程测试类
package org.bc.swagger.controller;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.bc.swagger.domain.Result;
import org.bc.swagger.domain.User;
import org.springframework.http.MediaType;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.*;
/**
*
* 用户管理
*
*/
@Api(value = "user", description = "用户管理", produces = MediaType.APPLICATION_JSON_VALUE)
@Controller
@RequestMapping("user")
public class UserController {
// 列出某个类目的所有规格
@ApiOperation(value = "获得用户列表", notes = "列表信息", httpMethod = "GET", produces = MediaType.APPLICATION_JSON_VALUE)
@ResponseBody
@RequestMapping(value = "list", method = RequestMethod.GET)
public Result<User> list(
@ApiParam(value = "分类ID", required = true) @RequestParam Long categoryId,
@ApiParam(value = "分类ID", required = true) @RequestParam Long categoryId2,
@ApiParam(value = "token", required = true) @RequestParam String token) {
Result<User> result = new Result<User>();
User user = new User();
user.setName("zhangsan");
user.setPassword("password");
user.setSex(1);
user.setToken("aastewetwewe97wewesf7w8");
result.setData(user);
return result;
}
@RequestMapping(value = "getUserById", method = RequestMethod.GET)
@ResponseBody
@ApiOperation(value = "根据id获得用户信息", notes = "用户信息", httpMethod = "GET", produces = MediaType.APPLICATION_JSON_VALUE)
public User getUserById(
@ApiParam(value = "user ID", required = true) @RequestParam String id
){
User user = new User();
user.setName("lisi");
user.setPassword("password");
user.setSex(1);
user.setToken("aastewetwewe97wewesf7w8");
return user;
}
@ApiOperation(value = "添加用户", notes = "添加用户(用于数据同步)", httpMethod = "POST", produces = MediaType.APPLICATION_JSON_VALUE)
@ResponseBody
@RequestMapping(value = "add", method = RequestMethod.POST)
// @RequestBody只能有1个
// 使用了@RequestBody,不能在拦截器中,获得流中的数据,再json转换,拦截器中,也不清楚数据的类型,无法转换成java对象
// 只能手动调用方法
public Result<String> add(@RequestBody User user) {
String u = findUser(user);
System.out.println(u);
return null;
}
@ApiOperation(value = "update用户", notes = "update user", httpMethod = "POST", produces = MediaType.APPLICATION_JSON_VALUE)
@ResponseBody
@RequestMapping(value = "update", method = RequestMethod.GET)
public Result<String> update(User user) {
String u = findUser(user);
System.out.println(u);
return null;
}
private String findUser(User user) {
String token = user.getToken();
return token;
}
}
4、编写启动类
package org.bc.swagger;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class SwaggerApp {
public static void main(String args[]){
System.out.println("test....");
SpringApplication.run(SwaggerApp.class);
}
}
5、说明
注解浏览
@Api : 在类上注解表名这个类是一个Swagger资源
@ApiImplicitParam 在API Operation中代表只有一个参数
@ApiImplicitParams 包装多个ApiImplicitParam对象
@ApiModel 关于Swagger模块提供额外的信息
@ApiModelProperty 添加和操作模型属性数据
@ApiOperation 描述一个操作或者通常针对特定路径的HTTP方法
@ApiParam 添加操作参数的额外元数据
@ApiResponse 描述一个操作可能的响应
@ApiResponses 包装多个ApiResponse对象
@Authorization声明对一个资源或者操作的授权
@AuthorizationScope 声明OAuth2授权范围
@ResponseHeader声明可以作为response的头部
详情请见:
http://jakubstas.com/spring-jersey-swagger-create-documentation/