Spring Boot Sample 033之swagger3.0
一、环境
- Idea 2020.1
- JDK 1.8
- maven
二、目的
spring boot 通过整合session的多种方式
gitHub地址： https://github.com/ouyushan/ouyushan-spring-boot-samples
三、步骤
3.1、点击File -> New Project -> Spring Initializer，点击next
3.2、在对应地方修改自己的项目信息
3.3、选择Web依赖，选中Spring Web。可以选择Spring Boot版本，本次默认为2.3.0，点击Next
3.4、项目结构
四、添加文件
相对比之前版本，只需一个依赖：
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
<?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.3.0.RELEASE</version>
<relativePath/> <!-- lookup parent from repository -->
</parent>
<groupId>org.ouyushan</groupId>
<artifactId>spring-boot-swagger</artifactId>
<version>0.0.1-SNAPSHOT</version>
<name>spring-boot-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>
<!-- swagger -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
<exclusions>
<exclusion>
<groupId>org.junit.vintage</groupId>
<artifactId>junit-vintage-engine</artifactId>
</exclusion>
</exclusions>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
</project>
在启动类和配置类上使用以下注解激活swagger
@EnableOpenApi
SwaggerConfiguration.java
package org.ouyushan.springboot.swagger.config;
import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpMethod;
import springfox.documentation.builders.*;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.schema.ScalarType;
import springfox.documentation.service.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import java.util.ArrayList;
import java.util.List;
/**
* @Description:
* @Author: ouyushan
* @Email: ouyushan@hotmail.com
* @Date: 2020/10/20 17:28
*/
@Configuration
@EnableOpenApi
public class SwaggerConfiguration {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.OAS_30)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
.paths(PathSelectors.any())
.build()
.globalRequestParameters(getGlobalRequestParameters())
.globalResponses(HttpMethod.GET, getGlobalResonseMessage())
.globalResponses(HttpMethod.POST, getGlobalResonseMessage());
}
//生成全局通用header参数
private List<RequestParameter> getGlobalRequestParameters() {
List<RequestParameter> parameters = new ArrayList<>();
parameters.add(new RequestParameterBuilder()
.name("ticket")
.description("ticket")
.required(true)
.in(ParameterType.HEADER)
.query(q -> q.model(m -> m.scalarModel(ScalarType.STRING)))
.build());
parameters.add(new RequestParameterBuilder()
.name("token")
.description("token")
.required(true)
.in(ParameterType.QUERY)
.query(q -> q.model(m -> m.scalarModel(ScalarType.STRING)))
.build());
return parameters;
}
//生成通用响应信息
private List<Response> getGlobalResonseMessage() {
List<Response> responseList = new ArrayList<>();
responseList.add(new ResponseBuilder().code("404").description("找不到资源").build());
return responseList;
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder().
title("swagger3.0")
.description("swagger3.0")
.contact(new Contact("ouyushan", "https://github.com/ouyushan","ouyushan@hotmail.com"))
.version("1.0")
.build();
}
}
实体类上使用：@ApiModel
属性使用：@ApiModelProperty
User.java
package org.ouyushan.springboot.swagger.entity;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
/**
* @Description: 实体类
* @Author: ouyushan
* @Email: ouyushan@hotmail.com
* @Date: 2020/11/13 9:15
*/
@ApiModel(value = "用户实体类")
public class User {
@ApiModelProperty(value = "用户id",example = "1")
private Integer id;
@ApiModelProperty(value = "用户名称",example = "ouyushan")
private String username;
@ApiModelProperty(value = "年龄",example = "24")
private Integer age;
public Integer getId() {
return id;
}
public void setId(Integer id) {
this.id = id;
}
public String getUsername() {
return username;
}
public void setUsername(String username) {
this.username = username;
}
public Integer getAge() {
return age;
}
public void setAge(Integer age) {
this.age = age;
}
public User() {
}
public User(Integer id, String username, Integer age) {
this.id = id;
this.username = username;
this.age = age;
}
}
UserService .java
package org.ouyushan.springboot.swagger.service;
import org.ouyushan.springboot.swagger.entity.User;
import org.springframework.stereotype.Service;
import java.util.*;
import java.util.function.Function;
import java.util.stream.Collectors;
/**
* @Description: service服务类
* @Author: ouyushan
* @Email: ouyushan@hotmail.com
* @Date: 2020/11/13 9:20
*/
@Service
public class UserService {
private List<User> userList = new ArrayList<>();
private Map<Integer, User> userMap = new HashMap<>();
public UserService() {
User user1 = new User(1, "jack", 23);
User user2 = new User(2, "jimmy", 24);
User user3 = new User(3, "tom", 25);
userList.add(user1);
userList.add(user2);
userList.add(user3);
userMap = userList.stream().collect(Collectors.toMap(User::getId, Function.identity()));
}
public User getUserById(Integer userId) {
return userMap.getOrDefault(userId, new User());
}
public List<User> getUserList() {
return userList;
}
}
接口类上使用@Api
类方法上使用@ApiOperation
UserController.java
package org.ouyushan.springboot.swagger.controller;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.ouyushan.springboot.swagger.entity.User;
import org.ouyushan.springboot.swagger.service.UserService;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import javax.annotation.Resource;
import java.util.List;
/**
* @Description:
* @Author: ouyushan
* @Email: ouyushan@hotmail.com
* @Date: 2020/11/12 20:53
*/
@Api("用户查询接口")
@RestController("/user")
public class UserController {
@Resource
private UserService userService;
@GetMapping("getById")
@ApiOperation(value = "根据用户id查询")
public User getUserById(Integer userId) {
return userService.getUserById(userId);
}
@GetMapping("getUserList")
@ApiOperation(value = "根据用户列表")
public List<User> getUserList() {
return userService.getUserList();
}
}
五、测试
运行启动类SpringBootSwaggerApplication
访问：
http://localhost:8080/swagger-ui/index.html#
点击右上角try it out 即可进行接口调用，其中ticket、token为配置的全局参数。
