Springfox集成Swagger2實戰篇

一   引入maven依賴

compile 'io.springfox:springfox-swagger2:2.9.2'
compile 'io.springfox:springfox-swagger-ui:2.9.2'
compile "io.springfox:springfox-bean-validators:2.9.2"

二 編寫配置文件

package com.wxbc.constant;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Import;
import springfox.bean.validators.configuration.BeanValidatorPluginsConfiguration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;
import java.util.List;

@Configuration
@EnableSwagger2
@Import(BeanValidatorPluginsConfiguration.class)
public class Swagger2 {
    @Bean
    public Docket createRestApi() {

         return new Docket(DocumentationType.SWAGGER_2)
         .select()
         .apis(RequestHandlerSelectors.any())
         .paths(PathSelectors.any())
         .build();  

    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("test平台端").description("可以直接訪問的接口")
                .version("0.1")
                .build();
    }

}

三 啟動項目訪問http://localhost:9079/swagger-ui.html

效果圖如下：

 

 

 

 

 四 Swagger2常用注解介紹

常用注解： 
- @Api()用於類； 
表示標識這個類是swagger的資源 , 一般作用於Controller上 

@Api(tags = "(查詢類api)")

- @ApiOperation()用於方法； 
表示一個http請求的操作 ，一般作用於接收http請示的方法上
- @ApiParam()用於方法，參數，字段說明； 
表示對參數的添加元數據（說明或是否必填等） 
- @ApiModel()用於類 
表示對類進行說明，用於參數用實體類接收 ，一般作用於@RequestBody的類上

- @ApiModelProperty()用於方法，字段 
表示對model屬性的說明或者數據操作更改 

- @ApiIgnore()用於類，方法，方法參數 

表示這個方法或者類被忽略 
- @ApiImplicitParam() 用於方法 
表示單獨的請求參數 
- @ApiImplicitParams() 用於方法，包含多個 @ApiImplicitParam

 

@ApiOperation(value = "test", notes = "test2",
        response = Response.class)
@PostMapping("/query")
public Response queryTransferDetail(@Valid @RequestBody QueryDetailPara para) throws ParameterException {
   
    return Response.success();
}

 

 

@ApiModel()用於類 ；表示對類進行說明，用於參數用實體類接收 
value–表示對象名 
description–描述 
都可省略 
@ApiModelProperty()用於方法，字段； 表示對model屬性的說明或者數據操作更改 
value–字段說明 
name–重寫屬性名字 
dataType–重寫屬性類型 
required–是否必填 
example–舉例說明 
hidden–是否對前端隱藏

@Data
@ApiModel
public class QueryDetailPara extends BaseInfo {

    @NotBlank(message = "project不能為空")
    @ApiModelProperty(value = "項目來源",required = true,example = "rhine3")
    @Size(min = 1,max = 65)
    private String project;

    @Max(100)
    @Min(10)
    @ApiModelProperty(value = "用戶年齡",allowableValues = "range[1,11]")
    private Integer age;

    @Max(100)
    @Min(10)
    @ApiModelProperty(value = "用戶年齡")
    private Integer age1;


    @Max(100)
    @Min(10)
    @ApiModelProperty(value = "用戶年齡",allowableValues = "10,100,1000")
    private Integer age2;

}

 

JSR 303：Bean Validation  允許您注釋Java類的字段以聲明約束和驗證規則。您可以使用以下規則注釋單個字段： - 不能為空，最小值，最大值，正則表達式匹配等。

一點說明：

1. @Max @Min注解 只能作用於Integer類的整形約束

2. 如果要修釋字符串的長度，使用@Size注解 

3.如果有些數據項需要枚舉值，可使用allowableValues,有三種寫法，

   i)  allowableValues="test1,test2,test3"

  ii)  allowableValues="range[1,11]"

  iii) allowableValues="range[1,infinity]"

  具體查看源碼：

 /**
     * Limits the acceptable values for this parameter.
     * <p>
     * There are three ways to describe the allowable values:
     * <ol>
     * <li>To set a list of values, provide a comma-separated list.
     * For example: {@code first, second, third}.</li>
     * <li>To set a range of values, start the value with "range", and surrounding by square
     * brackets include the minimum and maximum values, or round brackets for exclusive minimum and maximum values.
     * For example: {@code range[1, 5]}, {@code range(1, 5)}, {@code range[1, 5)}.</li>
     * <li>To set a minimum/maximum value, use the same format for range but use "infinity"
     * or "-infinity" as the second value. For example, {@code range[1, infinity]} means the
     * minimum allowable value of this parameter is 1.</li>
     * </ol>
     */
    String allowableValues() default "";

 

4. 使用allowableValues屬性會導致@Max @Min及@Size注解失效。

 

此文章純屬學習筆記，如有什么不足之處請在下方留言，我一會竭力改進