1 介绍

swagger和市面上的禅道、RAP2等众多图形化接口文档非常类似，经过短时间的摸索，和大量的查阅各类博客，记录下swagger2的使用和理解。

pom角度上讲，springfox-swagger2-ui集成了前端页面，并且不需要我们去管理，并且还可以使用yml预先编写接口，然后在按照HTML页面上进行开发。

2 前言

个人学习了一个技术，就会进行记录，所以这篇博客也是学习多篇博客，复制出来的内容。没有什么好写，直接放代码。

Swagger2 入门 - 图1

2.1 pom

  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <project xmlns="http://maven.apache.org/POM/4.0.0"
  3.          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  4.          xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  5.     <modelVersion>4.0.0</modelVersion>
  7.     <groupId>com.hikktn</groupId>
  8.     <artifactId>my-swagger2-test</artifactId>
  9.     <version>1.0-SNAPSHOT</version>
  11.     <parent>
  12.         <groupId>org.springframework.boot</groupId>
  13.         <artifactId>spring-boot-starter-parent</artifactId>
  14.         <version>2.1.4.RELEASE</version>
  15.     </parent>
  16.     <dependencies>
  17.         <dependency>
  18.             <groupId>io.springfox</groupId>
  19.             <artifactId>springfox-swagger2</artifactId>
  20.             <version>2.9.2</version>
  21.         </dependency>
  22.         <dependency>
  23.             <groupId>io.springfox</groupId>
  24.             <artifactId>springfox-swagger-ui</artifactId>
  25.             <version>2.9.2</version>
  26.         </dependency>
  27.         <!--fastjson-->
  28.         <dependency>
  29.             <groupId>com.alibaba</groupId>
  30.             <artifactId>fastjson</artifactId>
  31.             <version>1.2.51</version>
  32.         </dependency>
  34.         <!--测试包-->
  35.         <dependency>
  36.             <groupId>org.springframework.boot</groupId>
  37.             <artifactId>spring-boot-starter-test</artifactId>
  38.         </dependency>
  39.         <dependency>
  40.             <groupId>org.springframework.boot</groupId>
  41.             <artifactId>spring-boot-starter-web</artifactId>
  42.         </dependency>
  43.         <!-- 文件处理器-->
  44.         <dependency>
  45.             <groupId>org.springframework.boot</groupId>
  46.             <artifactId>spring-boot-configuration-processor</artifactId>
  47.             <optional>true</optional>
  48.         </dependency>
  51.     </dependencies>
  53. </project>

2.2 application.yml

  1. #swagger 配置
  2. swagger:
  3.   title: API示例
  4.   desc: 基于springBoot编写的RESful-API
  5.   version: 0.0.1.SNAPSHOT
  6.   termsOfServiceUrl: javascript:void(0)
  7.   license: Apache 2.0
  8.   licenseUrl: http://www.apache.org/licenses/LICENSE-2.0.html
  9.   # 监听的包路径
  10.   basePackage: com.hikktn.controller
  11.   groupName: 默认API示例分组
  12.   contactName: name
  13.   contactUrl: url
  14.   contactEmail: email
  15.   #生产环境改为false（改为false后swagger-ui.html则无法访问）
  16.   enable: true
  17.   #解决Swagger2 异常 NumberFormatException:For input string:""
  18.   logging:
  19.     level:
  20.       io:
  21.         swagger:
  22.           models:
  23.             parameters:
  24.               AbstractSerializableParameter: ERROR
  25. server:
  26.   port: 8080
  27.   servlet:
  28.     context-path: /

2.3 Swagger2Application

  1. package com.hikktn;
  3. import org.springframework.boot.SpringApplication;
  4. import org.springframework.boot.autoconfigure.SpringBootApplication;
  6. /**
  7.  * @ClassName Swagger2Application
  8.  * @Description 启动类
  9.  * @Author lisonglin
  10.  * @Date 2021/5/21 23:47
  11.  * @Version 1.0
  12.  */
  13. @SpringBootApplication
  14. public class Swagger2Application {
  16.     public static void main(String[] args){
  17.         SpringApplication.run(Swagger2Application.class,args);
  18.     }
  19. }

2.4 SwaggerConfig

  1. package com.hikktn.config;
  3. import io.swagger.annotations.ApiOperation;
  4. import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
  5. import org.springframework.boot.context.properties.ConfigurationProperties;
  6. import org.springframework.context.annotation.Bean;
  7. import org.springframework.context.annotation.Configuration;
  8. import org.springframework.http.ResponseEntity;
  9. import org.springframework.web.bind.annotation.RequestMethod;
  10. import org.springframework.web.servlet.config.annotation.EnableWebMvc;
  11. import springfox.documentation.builders.*;
  12. import springfox.documentation.schema.ModelRef;
  13. import springfox.documentation.service.ApiInfo;
  14. import springfox.documentation.service.Contact;
  15. import springfox.documentation.service.Parameter;
  16. import springfox.documentation.service.ResponseMessage;
  17. import springfox.documentation.spi.DocumentationType;
  18. import springfox.documentation.spring.web.plugins.Docket;
  19. import springfox.documentation.swagger2.annotations.EnableSwagger2;
  21. import java.time.LocalDate;
  22. import java.util.ArrayList;
  23. import java.util.List;
  26. @Configuration
  27. @EnableSwagger2
  28. @EnableWebMvc
  29. @ConfigurationProperties(prefix = "swagger")
  30. /**
  31.  * 生产环境禁用swagger2
  32.  */
  33. @ConditionalOnProperty(name = "swagger.enable", havingValue = "true")
  34. /**
  35.  * @ClassName SwaggerConfig
  36.  * @Description swagger2配置
  37.  * @Author lisonglin
  38.  * @Date 2021/5/21 23:38
  39.  * @Version 1.0
  40.  */
  41. public class SwaggerConfig {
  42.     private String title;
  43.     private String desc;
  44.     private String version;
  45.     private String termsOfServiceUrl;
  46.     private String license;
  47.     private String licenseUrl;
  48.     private String basePackage;
  49.     private String groupName;
  50.     private String contactName;
  51.     private String contactUrl;
  52.     private String contactEmail;
  54.     /**
  55.      * 增加API相关信息:包含作者、简介、版本、host、服务URL
  56.      * @return
  57.      */
  58.     private ApiInfo apiInfo() {
  59.         return new ApiInfoBuilder()
  60.                 //接口文档的标题
  61.                 .title(title)
  62.                 //文档描述
  63.                 .description(desc)
  64.                 //版本号
  65.                 .version(version)
  66.                 //服务条款URL
  67.                 .termsOfServiceUrl(termsOfServiceUrl)
  68.                 .licenseUrl(licenseUrl)
  69.                 //license 规范
  70.                 .license(license)
  71.                 // 开发文档的作者信息
  72.                 .contact(new Contact(contactName, contactUrl, contactEmail))
  73.                 .build();
  74.     }
  76.     @Bean
  77.     public Docket swaggerApi() {
  78.         //  ==================== 需要的参数 START ====================
  79.         List<Parameter> pars = new ArrayList<>();
  80.         ParameterBuilder token = new ParameterBuilder();
  81.         token.name("token").description("token").modelRef(new ModelRef("string")).parameterType("header").required(false).build();
  82.         pars.add(token.build());
  83.         //  ==================== 需要的参数 END ====================
  84.         return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).groupName(groupName)
  85.                 .directModelSubstitute(LocalDate.class, String.class).genericModelSubstitutes(ResponseEntity.class)
  86.                 .useDefaultResponseMessages(false)
  87.                 .globalResponseMessage(RequestMethod.POST, customerResponseMessage())
  88.                 .globalResponseMessage(RequestMethod.GET, customerResponseMessage())
  89.                 .forCodeGeneration(true).select()
  90.                 // api包扫描
  91.                 .apis(RequestHandlerSelectors.basePackage(basePackage))
  92.                 // 设置选择器
  93.                 .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
  94.                 .paths(PathSelectors.any())
  95.                 .build().globalOperationParameters(pars);
  96.     }
  98.     private List<ResponseMessage> customerResponseMessage() {
  99.         List<ResponseMessage> list = new ArrayList<>();
  100.         list.add(new ResponseMessageBuilder().code(200).message("请求成功").build());
  101.         list.add(new ResponseMessageBuilder().code(201).message("资源创建成功").build());
  102.         list.add(new ResponseMessageBuilder().code(204).message("服务器成功处理了请求，但不需要返回任何实体内容").build());
  103.         list.add(new ResponseMessageBuilder().code(400).message("请求失败,具体查看返回业务状态码与对应消息").build());
  104.         list.add(new ResponseMessageBuilder().code(401).message("请求失败,未经过身份认证").build());
  105.         list.add(new ResponseMessageBuilder().code(405).message("请求方法不支持").build());
  106.         list.add(new ResponseMessageBuilder().code(415).message("请求媒体类型不支持").build());
  107.         list.add(new ResponseMessageBuilder().code(500).message("服务器遇到了一个未曾预料的状况,导致了它无法完成对请求的处理").build());
  108.         list.add(new ResponseMessageBuilder().code(503).message("服务器当前无法处理请求,这个状况是临时的，并且将在一段时间以后恢复").build());
  109.         return list;
  110.     }
  112.     public String getTitle() {
  113.         return title;
  114.     }
  116.     public void setTitle(String title) {
  117.         this.title = title;
  118.     }
  120.     public String getDesc() {
  121.         return desc;
  122.     }
  124.     public void setDesc(String desc) {
  125.         this.desc = desc;
  126.     }
  128.     public String getVersion() {
  129.         return version;
  130.     }
  132.     public void setVersion(String version) {
  133.         this.version = version;
  134.     }
  136.     public String getTermsOfServiceUrl() {
  137.         return termsOfServiceUrl;
  138.     }
  140.     public void setTermsOfServiceUrl(String termsOfServiceUrl) {
  141.         this.termsOfServiceUrl = termsOfServiceUrl;
  142.     }
  144.     public String getLicense() {
  145.         return license;
  146.     }
  148.     public void setLicense(String license) {
  149.         this.license = license;
  150.     }
  152.     public String getLicenseUrl() {
  153.         return licenseUrl;
  154.     }
  156.     public void setLicenseUrl(String licenseUrl) {
  157.         this.licenseUrl = licenseUrl;
  158.     }
  160.     public String getBasePackage() {
  161.         return basePackage;
  162.     }
  164.     public void setBasePackage(String basePackage) {
  165.         this.basePackage = basePackage;
  166.     }
  168.     public String getGroupName() {
  169.         return groupName;
  170.     }
  172.     public void setGroupName(String groupName) {
  173.         this.groupName = groupName;
  174.     }
  176.     public String getContactName() {
  177.         return contactName;
  178.     }
  180.     public void setContactName(String contactName) {
  181.         this.contactName = contactName;
  182.     }
  184.     public String getContactUrl() {
  185.         return contactUrl;
  186.     }
  188.     public void setContactUrl(String contactUrl) {
  189.         this.contactUrl = contactUrl;
  190.     }
  192.     public String getContactEmail() {
  193.         return contactEmail;
  194.     }
  196.     public void setContactEmail(String contactEmail) {
  197.         this.contactEmail = contactEmail;
  198.     }
  199. }

2.5 WebMvcConfig

  1. package com.hikktn.config;
  3. import org.springframework.context.annotation.Configuration;
  4. import org.springframework.web.servlet.config.annotation.CorsRegistry;
  5. import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
  6. import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
  8. /**
  9.  * @ClassName WebMvcConfigurer
  10.  * @Description 前后端分离项目跨域访问
  11.  * @Author lisonglin
  12.  * @Date 2021/5/22 1:30
  13.  * @Version 1.0
  14.  */
  15. @Configuration
  16. public class WebMvcConfig implements WebMvcConfigurer {
  18.     public WebMvcConfig() {
  19.     }
  21.     @Override
  22.     public void addCorsMappings(CorsRegistry registry) {
  23.         registry.addMapping("/**").allowedOrigins(new String[]{"*"});
  24.     }
  26.     @Override
  27.     public void addResourceHandlers(ResourceHandlerRegistry registry) {
  28.         registry.addResourceHandler("/**").addResourceLocations(
  29.                 "classpath:/static/");
  30.         registry.addResourceHandler("swagger-ui.html")
  31.                 .addResourceLocations("classpath:/META-INF/resources/");
  33.         registry.addResourceHandler("/webjars/**")
  34.                 .addResourceLocations("classpath:/META-INF/resources/webjars/");
  35.     }
  37. }

2.6 UserController

  1. package com.hikktn.controller;
  3. import io.swagger.annotations.*;
  4. import org.springframework.http.ResponseEntity;
  5. import org.springframework.web.bind.annotation.*;
  7. import java.util.HashMap;
  8. import java.util.Map;
  10. /**
  11.  * @ClassName UserController
  12.  * @Description 用户服务控制器
  13.  * @Author lisonglin
  14.  * @Date 2021/5/21 23:39
  15.  * @Version 1.0
  16.  */
  17. @RestController
  18. @RequestMapping("user")
  19. @Api(tags = "用户服务接口")
  20. public class UserController {
  22.     @GetMapping("findAll")
  23.     @ApiOperation(value = "查询所有用户信息", notes = "查询所有用户信息接口")
  24.     public Map<String, Object> findAll() {
  25.         Map<String, Object> map = new HashMap<>();
  26.         map.put("success", "查询所有成功");
  27.         map.put("state", true);
  28.         return map;
  29.     }
  31.     @PostMapping("save")
  32.     @ApiOperation(value = "保存用户信息", notes = "保存用户信息接口")
  33.     @ApiImplicitParams({
  34.             @ApiImplicitParam(name = "id", value = "用户id", dataType = "String", defaultValue = "21"),
  35.             @ApiImplicitParam(name = "name", value = "用户名", dataType = "String", defaultValue = "zhangsan")
  36.     })
  37.     @ApiResponses({
  38.             @ApiResponse(code = 404, message = "页面不存在"),
  39.             @ApiResponse(code = 500, message = "服务器出错")
  40.     })
  41.     public Map<String, Object> sve(String id, String name) {
  42.         Map<String, Object> map = new HashMap<>();
  43.         map.put("success", "保存用户信息");
  44.         map.put("state", true);
  45.         return map;
  46.     }
  48.     @ApiOperation(value = "测试 - GET请求加入header参数")
  49.     @ApiImplicitParams({
  50.             @ApiImplicitParam(name = "token", value = "请求token", required = true, paramType = "header"),
  51.     })
  52.     @GetMapping
  53.     public ResponseEntity<String> test(@RequestHeader String token) {
  54.         return ResponseEntity.ok("token:" + token);
  55.     }
  56. }

3 测试

http://localhost:8080/swagger-ui.html

Swagger2 入门 - 图2

4、Swagger注解总结

A.官方总结

Swagger相关注解官方说明地址
https://github.com/swagger-api/swagger-core/wiki/Annotations

B.常见总结

@Api()用于类

标识这个类是swagger的资源
　　tags–表示分组说明标签

@ApiOperation()用于方法

表示一个http请求的操作
　　value用于方法描述
　　notes用于提示内容

@ApiModel()用于实体类

表示对类进行说明，用于参数用实体类接收
value–表示对象名
description–描述

@ApiModelProperty()用于实体类字段

表示对model属性的说明或者数据操作更改
　　value–字段说明
　　name–重写属性名字
　　dataType–重写属性类型
　　required–是否必填
　　example–举例说明
　　hidden–隐藏

@ApiImplicitParam() 用于 controller 方法

表示单独的请求参数
　　name–参数ming
　　value–参数说明
　　dataType–数据类型
　　paramType–参数类型
　　example–举例说明

@ApiImplicitParams() 用于 controller 方法

包含多个 @ApiImplicitParam

@ApiIgnore()用于类或者方法上

可以不被swagger显示在页面上