【Spring Boot】【四】swagger2注解使用教程

swagger2 注解整体说明

@Api：用在请求的类上，表示对类的说明
    tags="说明该类的作用，可以在UI界面上看到的注解"
    value="该参数没什么意义，在UI界面上也看不到，所以不需要配置"
    description="说明该类的作用，相当于子标题，可以在UI界面上看到的注解"

@ApiOperation：用在请求的方法上，说明方法的用途、作用
    value="说明方法的用途、作用"
    notes="方法的备注说明"

@ApiImplicitParams：用在请求的方法上，表示一组参数说明
    @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
        name：参数名
        value：参数的汉字说明、解释
        required：参数是否必须传
        paramType：参数放在哪个地方
            · header --> 请求参数的获取：@RequestHeader
            · query --> 请求参数的获取：@RequestParam
            · path（用于restful接口）--> 请求参数的获取：@PathVariable
            · body（不常用）
            · form（不常用）    
        dataType：参数类型，默认String，其它值dataType="Integer"       
        defaultValue：参数的默认值
@ApiParam：用在请求的参数上，指定一个请求参数的各个方面
    value="参数简单描述"
    required="是否为必传参数, false:非必传; true:必传"
    example="非请求体(body)类型的单个参数示例"
   defaultValue="描述参数默认值"
@ApiResponses：用在请求的方法上，表示一组响应
    @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
        code：数字，例如400
        message：信息，例如"请求参数没填好"
        response：抛出异常的类

@ApiModel：用于响应类上，表示一个返回响应数据的信息
            （这种一般用在post创建的时候，使用@RequestBody这样的场景，
            请求参数无法使用@ApiImplicitParam注解进行描述的时候）
    @ApiModelProperty：用在属性上，描述响应类的属性

1、 @Api：用在请求的类上，说明该类的作用

@Api：用在请求的类上，表示对类的说明
    tags="说明该类的作用，可以在UI界面上看到的注解"
    value="该参数没什么意义，在UI界面上也看不到，所以不需要配置"
    description="说明该类的作用，相当于子标题，可以在UI界面上看到的注解"

示例

@Api(tags="问好Tags",description="问好描述",value="问好value")

image.png

2、 @ApiOperation：用在请求的方法上，说明方法的作用

@ApiOperation："用在请求的方法上，说明方法的作用"
    value="说明方法的作用"
    notes="方法的备注说明"

示例

@ApiOperation(value = "hello value",notes="hello notes")

image.png

3、 @ApiImplicitParams：用在请求的方法上，包含一组参数说明

@ApiImplicitParams：用在请求的方法上，包含一组参数说明
    @ApiImplicitParam：用在 @ApiImplicitParams 注解中，指定一个请求参数的配置信息       
        name：参数名
        value：参数的汉字说明、解释
        required：参数是否必须传
        paramType：参数放在哪个地方
            · header --> 请求参数的获取：@RequestHeader
            · query --> 请求参数的获取：@RequestParam
            · path（用于restful接口）--> 请求参数的获取：@PathVariable
            · body（不常用）
            · form（不常用）    
        dataType：参数类型，默认String，其它值见附录1
        defaultValue：参数的默认值

示例

@ApiImplicitParams({
    @ApiImplicitParam(name="mobile",value="手机号",required=true,paramType="form"),
    @ApiImplicitParam(name="password",value="密码",required=true,paramType="form"),
    @ApiImplicitParam(name="age",value="年龄",required=true,paramType="form",dataType="int")
})

image.png

4、@ApiParam：用在请求的参数上，指定一个请求参数的各个方面

@ApiParam：用在请求的参数上，指定一个请求参数的各个方面
    value="参数简单描述"
    required="是否为必传参数, false:非必传; true:必传"
    example="非请求体(body)类型的单个参数示例"
   defaultValue="描述参数默认值"

示例

@ApiOperation(value = "获取学生")
    @GetMapping("/getStudent")
    public Student getStudent(
            @ApiParam(value = "姓名", required = false, example = "张三",defaultValue="李四") 
            @RequestParam(required = false) String name) {
        Student student = new Student();
        student.setMessage(name);
        return student;
    }

image.png

image.png

5、 @ApiResponses：用于请求的方法上，表示一组响应

@ApiResponses：用于请求的方法上，表示一组响应
    @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
        code：数字，例如400
        message：信息，例如"请求参数没填好"
        response：抛出异常的类

示例

@ApiResponses({
    @ApiResponse(code=400,message="请求参数没填好"),
    @ApiResponse(code=404,message="请求路径没有或页面跳转路径不对")
})

image.png

6、 @ApiModel：用于响应类上，表示一个返回响应数据的信息

@ApiModel：用于响应类上，表示一个返回响应数据的信息
            （这种一般用在post创建的时候，使用@RequestBody这样的场景，
            请求参数无法使用@ApiImplicitParam注解进行描述的时候）
    @ApiModelProperty：用在属性上，描述响应类的属性

示例

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel(description = "返回响应数据")
public class Student {
    @ApiModelProperty(value = "是否成功")
    private boolean success = true;
    @ApiModelProperty(value = "返回对象")
    private Object data;
    @ApiModelProperty(value = "错误编号")
    private Integer errCode;
    @ApiModelProperty(value = "错误信息")
    private String message;

    /* getter/setter */
}

image.png

附录

1、dataTypeApiimplicitparam的paramType

支持如下值：

package springfox.documentation.schema;

import com.fasterxml.classmate.ResolvedType;
import com.google.common.collect.ImmutableMap;
import org.springframework.web.multipart.MultipartFile;

import java.lang.reflect.Type;
import java.math.BigDecimal;
import java.math.BigInteger;
import java.util.Currency;
import java.util.Date;
import java.util.Map;
import java.util.Set;
import java.util.UUID;

import static com.google.common.collect.Sets.*;

public class Types {
  private Types() {
    throw new UnsupportedOperationException();
  }

  private static final Set baseTypes = newHashSet(
      "int",
      "date",
      "string",
      "double",
      "float",
      "boolean",
      "byte",
      "object",
      "long",
      "date-time",
      "__file",
      "biginteger",
      "bigdecimal",
      "uuid");
  private static final Map typeNameLookup = ImmutableMap.builder()
      .put(Long.TYPE, "long")
      .put(Short.TYPE, "int")
      .put(Integer.TYPE, "int")
      .put(Double.TYPE, "double")
      .put(Float.TYPE, "float")
      .put(Byte.TYPE, "byte")
      .put(Boolean.TYPE, "boolean")
      .put(Character.TYPE, "string")

      .put(Date.class, "date-time")
      .put(java.sql.Date.class, "date")
      .put(String.class, "string")
      .put(Object.class, "object")
      .put(Long.class, "long")
      .put(Integer.class, "int")
      .put(Short.class, "int")
      .put(Double.class, "double")
      .put(Float.class, "float")
      .put(Boolean.class, "boolean")
      .put(Byte.class, "byte")
      .put(BigDecimal.class, "bigdecimal")
      .put(BigInteger.class, "biginteger")
      .put(Currency.class, "string")
      .put(UUID.class, "uuid")
      .put(MultipartFile.class, "__file")
      .build();

  public static String typeNameFor(Type type) {
    return typeNameLookup.get(type);
  }

  public static boolean isBaseType(String typeName) {
    return baseTypes.contains(typeName);
  }

  public static boolean isBaseType(ResolvedType type) {
    return baseTypes.contains(typeNameFor(type.getErasedType()));
  }

  public static boolean isVoid(ResolvedType returnType) {
    return Void.class.equals(returnType.getErasedType()) || Void.TYPE.equals(returnType.getErasedType());
  }
}

2、开关控制

springboot整合swagger2并实现自定义开关

package com.example.hello;

import org.springframework.beans.factory.annotation.Value;
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 Swagger2 {
    @Value("${SWAGGER.ENABLE}")
    private boolean swaggerEnable;
    
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(swaggerEnable)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("测试Swagger工程")
                .description("测试学习一下")
                .contact(
                        new Contact("陈振林", "note.abeffect.com", "[email protected]")
                )
                .version("1.0.0-SNAPSHOT")
                .build();
    }
}

image.png

application配置文件添加SWAGGER.ENABLE来控制接口暴露的开关
SWAGGER.ENABLE=true 或者SWAGGER.ENABLE来控制接口是否展示

#Swagger开关
SWAGGER.ENABLE = false

3、拦截器

spring boot 加入拦截器后swagger不能访问问题
未加入拦截器时，swagger可以正常访问接口信息，但是加入拦截器之后swagger就不能访问了

原因分析

不能访问的原因的swagger的内置接口被拦截器拦下来了

image.png

图片中可以看到swagger的所有请求的url信息，只要把他们加到拦截器的排除列表中即可

package com.trimps928.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;

/**
 * @author liubing
 * @version 2018-06-26
 * 拦截器配置
 **/
@Configuration
public class MyWebAppConfig extends WebMvcConfigurationSupport {

    @Bean
    LoginInterceptor localInterceptor() {
        return new LoginInterceptor();
    }

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(localInterceptor())
                .excludePathPatterns("/user/login")
                .excludePathPatterns("/swagger-resources/**", "/webjars/**", "/v2/**", "/swagger-ui.html/**");
    }

    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

这两个方法都需要重写，只加任何一个都无法生效

4、解决Swagger2 异常：java.lang.NumberFormatException: For input string: ""

原文链接
访问swagger ui 时，会出现下面异常，虽然不影响使用，但是看着不爽。

2019-07-01 17:03:50.794  WARN 11252 --- [nio-8080-exec-1] i.s.m.p.AbstractSerializableParameter    : Illegal DefaultValue  for parameter type integer
 
java.lang.NumberFormatException: For input string: ""
    at java.lang.NumberFormatException.forInputString(NumberFormatException.java:65) ~[na:1.8.0_131]
    at java.lang.Long.parseLong(Long.java:601) ~[na:1.8.0_131]
    at java.lang.Long.valueOf(Long.java:803) ~[na:1.8.0_131]
    at io.swagger.models.parameters.AbstractSerializableParameter.getExample(AbstractSerializableParameter.java:412) ~[swagger-models-1.5.20.jar:1.5.20]
    at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method) ~[na:1.8.0_131]
    at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62) ~[na:1.8.0_131]
    at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43) ~[na:1.8.0_131]
    at java.lang.reflect.Method.invoke(Method.java:498) ~[na:1.8.0_131]
    at com.fasterxml.jackson.databind.ser.BeanPropertyWriter.serializeAsField(BeanPropertyWriter.java:688) [jackson-databind-2.9.9.jar:2.9.9]
    at com.fasterxml.jackson.databind.ser.std.BeanSerializerBase.serializeFields(BeanSerializerBase.java:719) [jackson-databind-2.9.9.jar:2.9.9]
    at com.fasterxml.jackson.databind.ser.BeanSerializer.serialize(BeanSerializer.java:155) [jackson-databind-2.9.9.jar:2.9.9]
    at com.fasterxml.jackson.databind.ser.impl.IndexedListSerializer.serializeContents(IndexedListSerializer.java:119) [jackson-databind-2.9.9.jar:2.9.9]
    at com.fasterxml.jackson.databind.ser.impl.IndexedListSerializer.serialize(IndexedListSerializer.java:79) [jackson-databind-2.9.9.jar:2.9.9]
    at com.fasterxml.jackson.databind.ser.impl.IndexedListSerializer.serialize(IndexedListSerializer

解决方案

排除springfox-swagger2 引入的swagger-annotations、swagger-models 1.5.20版本，手动引入1.5.21版本的jar

        
            io.springfox
            springfox-swagger2
            2.9.2
        
        
            io.springfox
            springfox-swagger-ui
            2.9.2
        
        
            io.swagger
            swagger-annotations
            1.5.21
        
        
            io.swagger
            swagger-models
            1.5.21