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的自动装配包

<?xml version="1.0"?>
<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"
    xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.3.3.RELEASE</version>
        <relativePath /> <!-- lookup parent from repository -->
    </parent>
    <groupId>com.badger</groupId>
    <artifactId>badger-spring-boot-securty</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>badger-spring-boot-securty</name>
    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <java.version>1.8</java.version>
        <maven-jar-plugin.version>3.1.1</maven-jar-plugin.version>
    </properties>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
            <exclusions>
                <exclusion>
                    <groupId>org.junit.vintage</groupId>
                    <artifactId>junit-vintage-engine</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

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", "286279186@qq.com"))
                .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#/