springboot项目配置swagger2示例详解

swagger简介

Swagger是一款RESTful接口的文档在线自动生成、功能测试功能框架。一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务，加上swagger-ui，可以有很好的呈现。

当我们在后台的接口修改了后，swagger可以实现自动的更新，而不需要人为的维护这个接口进行测试。

一、swagger2中常用的注解作用

二、springboot项目配置swagger2步骤

1、springboot项目的目录结构如下：

2、pom.xml文件引入如下配置

<!--引入web相关依赖-->
<dependency>
   <groupId>org.springframework.boot</groupId>
   <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!--引入swagger2-->
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger2</artifactId>
   <version>2.9.2</version>
</dependency>
<!--引入swagger-ui-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

3、application.yml配置文件配置如下

server:
 port: 8001 #端口
 servlet:
   context-path: /springSecurity #配置项目名称

4、Swagger配置文件如下：

package com.xz.springsecuritydemo.config;

import com.google.common.base.Predicate;
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 org.springframework.http.ResponseEntity;
import springfox.documentation.builders.ApiInfoBuilder;
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;
import static com.google.common.base.Predicates.or;
import static springfox.documentation.builders.PathSelectors.regex;

/**
* @description: Swagger配置文件
* @author: xz
*/
@Configuration
@EnableSwagger2//开启Swagger2
public class SwaggerConfig {

//注入配置文件中的项目名称
   @Value("${server.servlet.context-path}")
   private String contextPath;

/**
    * 构建 swagger2 api 文档的详细信息函数
    * @return
    */
   private ApiInfo initApiInfo() {
       ApiInfo apiInfo = new ApiInfoBuilder()
               .title("springSecurity测试项目 Platform API")//大标题
               .version( "1.0.0")//版本
               .description(initContextInfo())//描述
               .contact(new Contact("xz", "https://wwwxz.blog.csdn.net/", "123456@qq.com"))//作者信息
               .license("The System Server, Version 1.0")//网站链接显示文字
               .licenseUrl("https://wwwxz.blog.csdn.net/")//网站链接
               .build();

return apiInfo;
   }

private String initContextInfo() {
       StringBuffer sb = new StringBuffer();
       sb.append("REST API 设计在细节上有很多自己独特的需要注意的技巧，并且对开发人员在构架设计能力上比传统 API 有着更高的要求。")
               .append("<br/>")
               .append("本文通过翔实的叙述和一系列的范例，从整体结构，到局部细节，分析和解读了为了提高易用性和高效性，REST API 设计应该注意哪些问题以及如何解决这些问题。");

return sb.toString();
   }

/**
    * swagger2的配置文件，这里可以配置swagger2的一些基本的内容，比如扫描的包等等
    * @return
    */
   @Bean
   public Docket restfulApi() {
       System.out.println("http://localhost:8001" + contextPath + "/swagger-ui.html");
       return new Docket(DocumentationType.SWAGGER_2)
               .apiInfo(initApiInfo())
               .groupName("RestfulApi")
               //.genericModelSubstitutes(DeferredResult.class)
               .genericModelSubstitutes(ResponseEntity.class)
               .useDefaultResponseMessages(true)
               .forCodeGeneration(false)
               .pathMapping(contextPath) // base，最终调用接口后会和paths拼接在一起
               .select()
                //加了ApiOperation注解的类，才生成接口文档
                //.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                //暴露接口地址的包路径（即此包下的类，才生成接口文档）
               .apis(RequestHandlerSelectors.basePackage("com.xz.springsecuritydemo.modules.sys.controller"))
               .paths(doFilteringRules())//自定义的过滤规则
               .build();
   }

/**
    * 设置过滤规则
    * 这里的过滤规则支持正则匹配
    * @return
    */
   private Predicate<String> doFilteringRules() {
       return or(
               regex("/testUser.*"),
               regex("/hello.*")
       );
   }
}

5、用户实体类如下：

package com.xz.springsecuritydemo.modules.sys.entity;

import io.swagger.annotations.ApiModelProperty;
/**
* @description: 用户实体类
* @author: xz
*/
public class UserQueryCondition {
   private int id;
   @ApiModelProperty(value = "用户名称")
   private String name;
   private int age;

public int getId() {
       return id;
   }

public void setId(int id) {
       this.id = id;
   }

public String getName() {
       return name;
   }

public void setName(String name) {
       this.name = name;
   }

public int getAge() {
       return age;
   }

public void setAge(int age) {
       this.age = age;
   }
}

6、控制层代码如下：

package com.xz.springsecuritydemo.modules.sys.controller;

import com.xz.springsecuritydemo.modules.sys.entity.User;
import com.xz.springsecuritydemo.modules.sys.entity.UserQueryCondition;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.apache.commons.lang.builder.ReflectionToStringBuilder;
import org.apache.commons.lang.builder.ToStringStyle;
import org.springframework.web.bind.annotation.*;
/**
* @description: 控制层代码如下
* @author: xz
*/
@Api(value = "API - UserController",description = "用户模块接口详情")
@RestController
@RequestMapping("/testUser")
public class UserController {

/***
    *  @ApiParam 如果方法接受的是具体参数，此注解需要加到方法中的参数上
    */
   @RequestMapping(value = "/queryUserByName",method = RequestMethod.GET)
   @ApiOperation(value = "根据用户名称查询服务")
   public void queryUserByName(@ApiParam(value = "用户username") @RequestParam(name="username",required = false, defaultValue ="tom" ) String name){
       System.out.println("queryUser====="+name);
   }

/***
    * @ApiOperation 可用在方法头上.参数的描述容器
    * @ApiModelProperty 如果方法接受的是实体，此注解需要加到实体的具体属性上
    */
   @RequestMapping(value = "/queryUserAll",method = RequestMethod.GET)
   @ApiOperation(value = "根据用户id、名称和年龄查询服务")
   public void queryUserAll(UserQueryCondition userQueryCondition){
       //利用反射工具把对象输出
       System.out.println(ReflectionToStringBuilder.toString(userQueryCondition, ToStringStyle.MULTI_LINE_STYLE));
   }

/***
    * @ApiOperation 可用在方法头上.参数的描述容器
    */
   @PostMapping(value = "/createUser")
   @ApiOperation(value = "用户新增服务")
   public User userCreate1(@RequestBody User user){
       System.out.println(user.getName()+"----"+user.getPassword());
       user.setId(1);
       return user;
   }

/***
    * @ApiOperation 可用在方法头上.参数的描述容器
    */
   @PutMapping("/{id:\\d+}")
   @ApiOperation(value = "用户修改服务")
   public User update(@RequestBody User user){
       System.out.println(user.getId()+"======"+user.getName()+"----"+user.getPassword());
       user.setId(1);
       return user;
   }

/***
    * @ApiOperation 可用在方法头上.参数的描述容器
    */
   @DeleteMapping("/{id:\\d+}")
   @ApiOperation(value = "用户删除服务")
   public void delete(@PathVariable String id){
       System.out.println(id);
   }
}

7、启动项目，如下图：

8、启动项目后，访问 http://localhost:8001/springSecurity/swagger-ui.html，如下图：

9、点击user-Controller,如下图所示：

10、点击具体某一方法，可以看到如下信息：

三、示例中使用的注解解析

1、@Api注解标注在了控制层的UserController类上，如下图画红色框的位置可以看到注解生效。

2、@ApiOperation注解标注在了控制层的UserController类的方法上，如下图画红色框的位置可以看到注解生效。

3、@ApiParam注解标注在了控制层的方法参数上，如下图画红色框的位置可以看到注解生效。

4、@ApiModelProperty注解标注在了实体中的属性上，在控制层方法接收实体对象时生效，如下图画红色框的位置可以看到注解生效。

来源：https://blog.csdn.net/li1325169021/article/details/120297805