springboot之spring-boot 2.3.x 整合swagger3.0.0

spring-boot 2.3.x 整合swagger3.0.0

 

 

环境	版本
jdk	1.8.0_201
maven	3.6.0
Spring-boot	2.3.3.RELEASE

1、简介

Swagger UI 是一款 API 在线文档生成和调试工具。在需求不断变更的开发环境下，手动编写文档的效率实在太低；

在Swagger3版本中，减少了谷歌的guava依赖，更多的应用了java8的语法；新增了springboot流行的start启动包形式依赖；

主要配置属性如下：主要说一些常用的配置

@Api(tags = "测试接口")：用在请求的controller类上，表示对类的说明，tags=“说明该类的作用，可以在UI界面上看到的注解”

@ApiOperation("测试")：用在请求的方法上；value=方法的用途；notes=“方法的备注”

@ApiResponses：用在请求的方法上，表示一组响应;

​ @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
code：请求的状态码，例如 200、401、403 ……
message：信息，例如"请求参数没填好"

@ApiImplicitParams：用在请求的方法上，表示一组参数说明;

@ApiImplicitParam：用在方法上，表示一个请求参数描述；多在参与，用在@ApiImplicitParams中；

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface ApiImplicitParam {
   	//参数名
    String name() default "";
    //参数描述
    String value() default "";
    //参数默认值
    String defaultValue() default "";

    String allowableValues() default "";
   	//是否必传
    boolean required() default false;

    String access() default "";
   	//允许多个，当传入的参数为数组或者list时候，指定参数类型dataType()，属性设置为true；
    boolean allowMultiple() default false;
		//数据类型：这可以是类名或基础类型。
    String dataType() default "";
		//数据的class类
    Class dataTypeClass() default Void.class;
    /**
    	请求参数类型：
    				path：请求参数的获取：@PathVariable
    				query：请求参数的获取：@RequestParam
    				body：@RequestBody
    				header：请求参数的获取：@RequestHeader
    				form：表单数据
     */
    String paramType() default "";
    /** a single example for non-body type parameters*/
    String example() default "";
   //Examples for the parameter.  Applies only to BodyParameters
    Example examples() default @Example(value = @ExampleProperty(mediaType = "", value = ""));
  	//Adds the ability to override the detected type
    String type() default "";
		//Adds the ability to provide a custom format
    String format() default "";
		//Adds the ability to set a format as empty
    boolean allowEmptyValue() default false;
		//adds ability to be designated as read only.
    boolean readOnly() default false;
		//adds ability to override collectionFormat with `array` types
    String collectionFormat() default "";
}

@ApiModel:用于类上，表示一个返回响应数据的信息，或者传入的参数对象的内容：例如post请求；

@ApiModelProperty：用在属性上，描述响应类的属性

详细可以参看《github springfox》

2、构建一个基础的web项目

2.1、导入swagger的自动装配包

    4.0.0
    
        org.springframework.boot
        spring-boot-starter-parent
        2.3.3.RELEASE
         
    
    com.badger
    badger-spring-boot-securty
    0.0.1-SNAPSHOT
    badger-spring-boot-securty
    
        UTF-8
        1.8
        3.1.1
    
    
        
            org.springframework.boot
            spring-boot-starter-web
        
        
            io.springfox
            springfox-boot-starter
            3.0.0
        
        
            org.springframework.boot
            spring-boot-starter-test
            test
            
                
                    org.junit.vintage
                    junit-vintage-engine
                
            
        
    

    
        
            
                org.springframework.boot
                spring-boot-maven-plugin
            
        
    

2.2、swagger的配置类

/**
 * 基于Swagger生成API文档
 * @EnableOpenApi：启动OpenApi的类； 之前是@EnableSwagger2

 */
@Configuration
@EnableOpenApi
public class SwaggerConfiguration {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30).apiInfo(apiInfo()).select()
                .apis(RequestHandlerSelectors.basePackage("com.badger.spring.boot.web")).paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("我是标题").description("我是描述").contact(new Contact("联系人", "www.baidu.com", "[email protected]"))
                .version("1.0").build();
    }

}

2.3、主启动类

@Api(tags = "测试接口")
@RestController
@SpringBootApplication
public class SwaggerApplication {

    public static void main(String[] args) throws Exception {
        SpringApplication.run(SwaggerApplication.class, args);
    }

    @ApiResponse(message = "测试", code = 200)
    @ApiOperation("ceshi")
    @GetMapping("/test")
    public String test() {
        return "test";
    }
}

3、测试演示

直接启动springboot的启动类就可以了

访问地址 http://localhost:8080/swagger-ui/index.html#/