SpringBoot项目中引入Swagger

在SpringBoot项目中引入Swagger，让接口数据可视化，尤其适用于Restful API
本案例使用工具：IDEA
本案例GitHub地址:https://github.com/limenggen/springboot-swagger-demo

1、创建一个SpringBoot项目

• 项目结构
  

2、引入swagger依赖

pom.xml

• 引入swagger原生依赖：springfox-swagger2和springfox-swagger-ui

  1 2 3 4 5 6 7 8 9 10 11

  <!-- 引入swagger2依赖--> <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>

  • 相关依赖需要注意版本
  • 本案例依赖版本：
  • spring-boot-starter-web:2.3.4
  • mybatis-spring-boot-starter:2.3.4
  • springfox-swagger2:2.9.2
  • springfox-swagger-ui:2.9.2
  • lombok:1.18.12

3、修改配置文件

修改application.properties文件为application.yml

1
2
3
4
5
6
7
8
9
10
11
12

server:
  port: 8081
swagger:
  base-path: /**
  base-package: 'com.morgan.controller'
  title: 'spring-boot-swagger'
  description: '基于Swagger构建的SpringBoot RestApi 文档'
  version: '1.0'
  contact:
    name: 'morgan'
    url: 'https://github.com/limenggen/springboot-swagger'
    email: 'xxx@163.com'

4、新建一个swagger配置类

SwaggerConfig.java

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

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.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    /**
    * 通过createRestApi函数构造一个DocketBean
    * 函数名，可以随意命名
    */
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())// 调用apiInfo方法，创建一个ApiInfo实例，里面是展示在文档页面信息
                .select() // 控制暴露出去的路径下的实例，若某个接口不想暴露，可以用@ApiIgnore注解，则该接口就不会出现在swagger2页面下
                .apis(RequestHandlerSelectors.basePackage("com.morgan.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    // 构建api文档的详细信息函数
    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("基于Swagger构建的Rest API文档")
                .description("更多请咨询服务开发者morgan")
                .contact(new Contact("Morgan", "http://limenggen.gitee.io","xxx@163.com"))
                .termsOfServiceUrl("http://limenggen.gitee.io")
                .version("1.0")
                .build();
    }
    }

5、添加实体类

User.java

• @ApiModel：描述返回对象的意义,用在返回对象类上
• ApiModelProperty：对象属性， 用在出入参数对象的字段上

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25

  import io.swagger.annotations.ApiModel; import io.swagger.annotations.ApiModelProperty; import lombok.AllArgsConstructor; import lombok.Data; import java.util.Date; @Data @AllArgsConstructor @ApiModel(description = "用户类") public class User { @ApiModelProperty(value = "ID", example = "100") private Integer id; @ApiModelProperty(value = "姓名", example = "laolunsi") private String name; @ApiModelProperty(value = "是否启用", example = "1") private Boolean enable; @ApiModelProperty("更新时间") private Date updateTime; }

6、创建Controller类

添加swagger、RestController注解

• @Api：协议集描述， 用于controller类上
• @ApiOperation：协议描述，用在controller的方法上

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58

  import com.morgan.entity.User; import io.swagger.annotations.Api; import io.swagger.annotations.ApiOperation; import io.swagger.annotations.ApiParam; import org.springframework.util.StringUtils; import org.springframework.web.bind.annotation.*; import java.util.ArrayList; import java.util.Date; import java.util.List; import java.util.Map; import java.util.concurrent.ConcurrentHashMap; @Api(tags = "用户管理") @RestController @RequestMapping(value = "user") public class testController { private static Map<Integer, User> userMap; static { userMap = new ConcurrentHashMap<>(); User user = new User(100, "admin", true, new Date()); } @ApiOperation("列表查询") @GetMapping(value = "list") public List<User> list(){ return new ArrayList<>(userMap.values()); } @ApiOperation(value = "获取用户详细信息", notes = "路径参数ID") @GetMapping(value = "{id}") public User detail(@PathVariable Integer id){ return userMap.get(id); } @ApiOperation(value = "新增或更新用户信息", notes = "insert和update共用", response = User.class) @PostMapping(value = "add") public User add(@RequestBody User user){ if(user == null || user.getId() == null || StringUtils.isEmpty(user.getName()) || userMap.containsKey(user.getId())){ return null; } user.setUpdateTime(new Date()); userMap.put(user.getId(), user); return user; } @ApiOperation(value = "删除用户") @GetMapping(value = "del/{id}") public Boolean delete(@ApiParam(name = "用户ID", required = true, example = "100") Integer id){ if(userMap.containsKey(id)){ userMap.remove(id); return true; } return false; } }

7、启动项目

项目访问地址：http://localhost:8081/swagger-ui.html