8.Spring Boot 中使用 swagger

2020年01月19日 11:08 · 阅读(553) ·

Spring Boot

目标

在 Spring Boot 项目中使用 swagger 进行接口测试

开发环境

名称 版本
操作系统 Windows 10 X64
JDK JDK1.8（jdk-8u151-windows-x64）
IntelliJ IDEA IntelliJ IDEA 2018.3
Maven Maven 3.6.0
swagger2 2.7.0
swagger-ui 2.7.0

说明

本文代码基于 7.Spring Boot 中使用 Redis 数据库 的基础上进行修改

test-invoice-web

pom.xml

  1. <properties>
  2.     <swagger.version>2.7.0</swagger.version>
  3.     <swagger-ui.version>2.7.0</swagger-ui.version>
  4. </properties>    
  6. <dependencies>
  7.     <!--swagger start-->
  8.     <!--springfox是通过注解的形式自动生成API文档，利用它，可以很方便的书写restful API，swagger主要用于展示springfox生成的API文档-->
  9.     <dependency>
  10.         <groupId>io.springfox</groupId>
  11.         <artifactId>springfox-swagger2</artifactId>
  12.         <version>${swagger.version}</version>
  13.     </dependency>
  15.     <dependency>
  16.         <groupId>io.springfox</groupId>
  17.         <artifactId>springfox-swagger-ui</artifactId>
  18.         <version>${swagger-ui.version}</version>
  19.     </dependency>
  20.     <!--swagger end-->
  21. </dependencies>

application.yml

  1. # 是否显示swagger-ui
  2. swagger.show: true

Swagger 配置类-SwaggerConfig

  1. package com.test.invoice.config;
  3. import com.alibaba.fastjson.annotation.JSONField;
  4. import com.fasterxml.jackson.databind.ObjectMapper;
  5. import com.fasterxml.jackson.databind.PropertyName;
  6. import com.fasterxml.jackson.databind.introspect.Annotated;
  7. import com.fasterxml.jackson.databind.introspect.JacksonAnnotationIntrospector;
  8. import com.fasterxml.jackson.databind.module.SimpleModule;
  9. import org.springframework.beans.factory.annotation.Autowired;
  10. import org.springframework.beans.factory.annotation.Value;
  11. import org.springframework.context.ApplicationContext;
  12. import org.springframework.context.annotation.Bean;
  13. import org.springframework.context.annotation.Configuration;
  14. import org.springframework.web.context.request.async.DeferredResult;
  15. import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;
  16. import springfox.documentation.builders.ApiInfoBuilder;
  17. import springfox.documentation.builders.RequestHandlerSelectors;
  18. import springfox.documentation.schema.configuration.ObjectMapperConfigured;
  19. import springfox.documentation.service.ApiInfo;
  20. import springfox.documentation.spi.DocumentationType;
  21. import springfox.documentation.spring.web.plugins.Docket;
  22. import springfox.documentation.swagger2.annotations.EnableSwagger2;
  24. import javax.annotation.PostConstruct;
  25. import java.lang.annotation.Annotation;
  27. /**
  28.  * Swagger 配置类
  29.  *
  30.  * @author: 
  31.  * @date: 2020-01-17 16:26
  32.  */
  33. @Configuration
  34. @EnableSwagger2
  35. public class SwaggerConfig extends WebMvcConfigurerAdapter {
  36.     @Value("${swagger.show}")
  37.     private boolean enableSwagger;
  40.     @Autowired
  41.     private ApplicationContext applicationContext;
  44.     @PostConstruct
  45.     public void setObjectMapper() {
  46.         ObjectMapper objectMapper = new ObjectMapper();
  47.         SimpleModule module = new SimpleModule();
  48.         objectMapper.registerModule(module);
  50.         JacksonAnnotationIntrospector jacksonAnnotationIntrospector=  new JacksonAnnotationIntrospector();
  52.         objectMapper.setAnnotationIntrospector(new JacksonAnnotationIntrospector() {
  54.             @Override
  55.             public boolean isAnnotationBundle(Annotation ann) {
  56.                 if (ann.annotationType() == JSONField.class) {
  57.                     return true;
  58.                 }
  59.                 return super.isAnnotationBundle(ann);
  60.             }
  62.             @Override
  63.             public PropertyName findNameForSerialization(Annotated a) {
  64.                 PropertyName nameForSerialization = super.findNameForSerialization(a);
  65.                 if (nameForSerialization == null || nameForSerialization == PropertyName.USE_DEFAULT) {
  66.                     JSONField jsonField = _findAnnotation(a, JSONField.class);
  67.                     if (jsonField != null) {
  68.                         return PropertyName.construct(jsonField.name());
  69.                     }
  70.                 }
  71.                 return nameForSerialization;
  72.             }
  74.             @Override
  75.             public PropertyName findNameForDeserialization(Annotated a) {
  76.                 PropertyName nameForDeserialization = super.findNameForDeserialization(a);
  77.                 if (nameForDeserialization == null || nameForDeserialization == PropertyName.USE_DEFAULT) {
  78.                     JSONField jsonField = _findAnnotation(a, JSONField.class);
  79.                     if (jsonField != null) {
  80.                         return PropertyName.construct(jsonField.name());
  81.                     }
  82.                 }
  83.                 return nameForDeserialization;
  84.             }
  85.         });
  87.         ObjectMapperConfigured objectMapperConfigured = new ObjectMapperConfigured(applicationContext, objectMapper);
  88.         applicationContext.publishEvent(objectMapperConfigured);
  89.     }
  92.     @Bean
  93.     public Docket api() {
  94.         return new Docket(DocumentationType.SWAGGER_2).groupName("framework").enable(enableSwagger)
  95.                 .genericModelSubstitutes(DeferredResult.class).useDefaultResponseMessages(false)
  96.                 .forCodeGeneration(false).pathMapping("/").apiInfo(apiInfo()).select()
  97.                 .apis(RequestHandlerSelectors.basePackage("com.test.invoice.control")).build();
  98.         //com.test.invoice.controller
  99.         //package com.foreign.payment.web.controller
  100.     }
  102.     private ApiInfo apiInfo() {
  103.         return new ApiInfoBuilder().title("应用框架").description("平台接口文档").termsOfServiceUrl("")
  104.                 .contact("测试项目").version("1.0").build();
  105.     }
  106. }

MVC 配置类-WebMVCConfig

  1. package com.test.invoice.config;
  3. import org.springframework.context.annotation.Configuration;
  4. import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
  5. import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;
  7. /**
  8.  * Created by  on 2019/4/9.
  9.  * 是因为swagger-ui.html 是在springfox-swagger-ui.jar里的，因为修改了路径Spring Boot不会自动把/swagger-ui.html这个路径映射到对应的目录META-INF/resources/下面。
  10.  *所以我们修改springboot配置类，为swagger建立新的静态文件路径映射就可以了
  11.  *原文：https://blog.csdn.net/weixin_39168678/article/details/80563402
  12.  */
  13. @Configuration
  14. public class WebMVCConfig extends WebMvcConfigurerAdapter {
  15.     @Override
  16.     public void addResourceHandlers(ResourceHandlerRegistry registry) {
  17.         registry.addResourceHandler("swagger-ui.html")
  18.                 .addResourceLocations("classpath:/META-INF/resources/");
  19.         registry.addResourceHandler("/webjars/**")
  20.                 .addResourceLocations("classpath:/META-INF/resources/webjars/");
  22.     }
  23. }

测试类-TRbtTestController

  1. package com.test.invoice.controller;
  3. import com.alibaba.fastjson.JSON;
  4. import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
  5. import com.google.gson.Gson;
  6. import com.google.gson.GsonBuilder;
  7. import com.test.invoice.data.TRbtTestData;
  8. import com.test.invoice.data.TRbtTestDataParam;
  9. import com.test.invoice.enums.ResponseCode;
  10. import com.test.invoice.model.TRbtTestEntity;
  11. import com.test.invoice.model.TRbtUserEntity;
  12. import com.test.invoice.model.base.SuperEntity;
  13. import com.test.invoice.service.consumer.TRbtTestConsumer;
  14. import com.test.invoice.util.*;
  15. import com.test.invoice.vo.LoginRequestVO;
  16. import com.test.invoice.vo.ResponseVO;
  17. import io.swagger.annotations.Api;
  18. import io.swagger.annotations.ApiImplicitParam;
  19. import io.swagger.annotations.ApiImplicitParams;
  20. import io.swagger.annotations.ApiOperation;
  21. import lombok.extern.slf4j.Slf4j;
  22. import org.apache.commons.lang3.StringUtils;
  23. import org.springframework.web.bind.annotation.*;
  24. import org.springframework.beans.factory.annotation.Autowired;
  26. import javax.servlet.http.HttpServletRequest;
  27. import javax.ws.rs.POST;
  28. import java.net.URLEncoder;
  29. import java.time.LocalDate;
  30. import java.util.ArrayList;
  31. import java.util.HashMap;
  32. import java.util.List;
  33. import java.util.Map;
  35. /**
  36.  * 消费者，通过 Feign-api 调用
  37.  *
  38.  * @author:
  39.  * @version:
  40.  * @date: 2019-08-12 14:49
  41.  */
  42. @RestController
  43. @Api(description = "测试框架系统控制类")
  44. @RequestMapping("/Inv/Api")
  45. @Slf4j
  46. public class TRbtTestController {
  47.     /**
  48.      * ClassToJson
  49.      * @param data TRbtTestData
  50.      * @param convertType 1:使用 GSON 转换，2:使用 alibaba.fastjson 转换
  51.      * @return JsonString
  52.      */
  53.     @PostMapping("/Test/ClassToJson")
  54.     @ApiOperation(value = "类转 Json",httpMethod = "POST",response = ResponseVO.class,notes="类转 Json")
  55.     public ResponseVO ClassToJson(@RequestBody TRbtTestData data,@RequestParam(value="convertType",required = true) String convertType)
  56.     {
  57.         ResponseVO responseVO = new ResponseVO<String>();
  58.         if (convertType.equals("1")){
  59.             GsonBuilder builder = new GsonBuilder();
  60.             Gson gson = builder.create();
  61.             responseVO.setData(gson.toJson(data));
  62.         }else if (convertType.equals("2")){
  63.             responseVO.setData(JSON.toJSONString(data));
  64.         }
  66.         responseVO.setCode(ResponseCode.OK.value());
  68.         return responseVO;
  69.     }
  72.     /**
  73.      *  WebClientTest
  74.      * @return String
  75.      */
  76.     @PostMapping("/Test/PinYin")
  77.     @ApiImplicitParams({@ApiImplicitParam(paramType = "header", name = "Authorization", value = "凭证", required = true, dataType = "string"),})
  78.     public ResponseVO PinYin(){
  79.         ResponseVO responseVO = new ResponseVO<String>();
  81.         CharacterPinYinConvert convert = new CharacterPinYinConvert();
  82.         responseVO.setData(convert.toPinYin("罗马")+"======"+convert.toPinYins("一加一的和等于二"));
  83.         return responseVO;
  84.     }
  85. }

测试

浏览器访问 http://localhost:8080//swagger-ui.html

测试-ClassToJson

测试-PinYin

Spring Boot3-OpenAPI 3 与 Swagger

整合

  • 导入场景
  1. <dependency>
  2.     <groupId>org.springdoc</groupId>
  3.     <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
  4.     <version>2.1.0</version>
  5. </dependency>
  • 配置
  1. # /api-docs endpoint custom path 默认 /v3/api-docs
  2. springdoc.api-docs.path=/api-docs
  4. # swagger 相关配置在  springdoc.swagger-ui
  5. # swagger-ui custom path
  6. springdoc.swagger-ui.path=/swagger-ui.html
  8. springdoc.show-actuator=true

使用

1.常用注解

注解 标注位置 作用
@Tag controller 类 标识 controller 作用
@Parameter 参数 标识参数作用
@Parameters 参数 参数多重说明
@Schema model 层的 JavaBean 描述模型作用及每个属性
@Operation 方法 描述方法作用
@ApiResponse 方法 描述响应状态码等

2.Docket配置

如果有多个 Docket，配置如下

  1.   @Bean
  2.   public GroupedOpenApi publicApi() {
  3.       return GroupedOpenApi.builder()
  4.               .group("springshop-public")
  5.               .pathsToMatch("/public/**")
  6.               .build();
  7.   }
  8.   @Bean
  9.   public GroupedOpenApi adminApi() {
  10.       return GroupedOpenApi.builder()
  11.               .group("springshop-admin")
  12.               .pathsToMatch("/admin/**")
  13.               .addMethodFilter(method -> method.isAnnotationPresent(Admin.class))
  14.               .build();
  15.   }

如果只有一个 Docket，可以配置如下

  1. springdoc.packagesToScan=package1, package2
  2. springdoc.pathsToMatch=/v1, /api/balance/**

3.OpenAPI 配置

  1.   @Bean
  2.   public OpenAPI springShopOpenAPI() {
  3.       return new OpenAPI()
  4.               .info(new Info().title("SpringShop API")
  5.               .description("Spring shop sample application")
  6.               .version("v0.0.1")
  7.               .license(new License().name("Apache 2.0").url("http://springdoc.org")))
  8.               .externalDocs(new ExternalDocumentation()
  9.               .description("SpringShop Wiki Documentation")
  10.               .url("https://springshop.wiki.github.org/docs"));
  11.   }

Springfox 迁移

1.注解变化

原注解 现注解 作用
@Api @Tag 描述 Controller
@ApiIgnore @Parameter(hidden = true)
@Operation(hidden = true)
@Hidden		 描述忽略操作
@ApiImplicitParam @Parameter 描述参数
@ApiImplicitParams @Parameters 描述参数
@ApiModel @Schema 描述对象
@ApiModelProperty(hidden = true) @Schema(accessMode = READ_ONLY) 描述对象属性
@ApiModelProperty @Schema 描述对象属性
@ApiOperation(value = “foo”, notes = “bar”) @Operation(summary = “foo”, description = “bar”) 描述方法
@ApiParam @Parameter 描述参数
@ApiResponse(code = 404, message = “foo”) @ApiResponse(responseCode = “404”, description = “foo”) 描述响应

2.Docket 配置

(1)以前写法

  1.   @Bean
  2.   public Docket publicApi() {
  3.       return new Docket(DocumentationType.SWAGGER_2)
  4.               .select()
  5.               .apis(RequestHandlerSelectors.basePackage("org.github.springshop.web.public"))
  6.               .paths(PathSelectors.regex("/public.*"))
  7.               .build()
  8.               .groupName("springshop-public")
  9.               .apiInfo(apiInfo());
  10.   }
  12.   @Bean
  13.   public Docket adminApi() {
  14.       return new Docket(DocumentationType.SWAGGER_2)
  15.               .select()
  16.               .apis(RequestHandlerSelectors.basePackage("org.github.springshop.web.admin"))
  17.               .paths(PathSelectors.regex("/admin.*"))
  18.               .apis(RequestHandlerSelectors.withMethodAnnotation(Admin.class))
  19.               .build()
  20.               .groupName("springshop-admin")
  21.               .apiInfo(apiInfo());
  22.   }

(2)新写法

  1.   @Bean
  2.   public GroupedOpenApi publicApi() {
  3.       return GroupedOpenApi.builder()
  4.               .group("springshop-public")
  5.               .pathsToMatch("/public/**")
  6.               .build();
  7.   }
  8.   @Bean
  9.   public GroupedOpenApi adminApi() {
  10.       return GroupedOpenApi.builder()
  11.               .group("springshop-admin")
  12.               .pathsToMatch("/admin/**")
  13.               .addOpenApiMethodFilter(method -> method.isAnnotationPresent(Admin.class))
  14.               .build();
  15.   }

(3)添加 OpenAPI 组件

  1.   @Bean
  2.   public OpenAPI springShopOpenAPI() {
  3.       return new OpenAPI()
  4.               .info(new Info().title("SpringShop API")
  5.               .description("Spring shop sample application")
  6.               .version("v0.0.1")
  7.               .license(new License().name("Apache 2.0").url("http://springdoc.org")))
  8.               .externalDocs(new ExternalDocumentation()
  9.               .description("SpringShop Wiki Documentation")
  10.               .url("https://springshop.wiki.github.org/docs"));
  11.   }