spring-boot 2.3.x 整合swagger3.0.0

以你之姓@ 2021-09-24 16:06 358阅读 0赞

# spring-boot 2.3.x 整合swagger3.0.0 #

### 文章目录 ###

*  spring-boot 2.3.x 整合swagger3.0.0
 *   *  1、简介
     *  2、构建一个基础的web项目
     *   *  2.1、导入swagger的自动装配包
         *  2.2、swagger的配置类
         *  2.3、主启动类
     *  3、测试演示

本地项目的基础环境

<table> 
 <thead> 
  <tr> 
   <th align="center">环境</th> 
   <th align="center">版本</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="center">jdk</td> 
   <td align="center">1.8.0_201</td> 
  </tr> 
  <tr> 
   <td align="center">maven</td> 
   <td align="center">3.6.0</td> 
  </tr> 
  <tr> 
   <td align="center">Spring-boot</td> 
   <td align="center">2.3.3.RELEASE</td> 
  </tr> 
 </tbody> 
</table>

## 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》][github springfox]

![aa733f91a04978ea539e17337fccd9b8.png][]

## 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 /> 
        </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 * @author: liqi */
    @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\#/][http_localhost_8080_swagger-ui_index.html]

![c067e145ce6a53f0b0d964bf3adb1944.png][]

详细代码也可以参看[《码云》][Link 1]

[github springfox]: https://github.com/springfox/springfox
[aa733f91a04978ea539e17337fccd9b8.png]: /images/20210923/3f0f8692d09f4d089b8dcc309a996203.png
[http_localhost_8080_swagger-ui_index.html]: http://localhost:8080/swagger-ui/index.html#/
[c067e145ce6a53f0b0d964bf3adb1944.png]: /images/20210923/f26f6f2548274346a09e32de34494880.png
[Link 1]: https://gitee.com/liqi01/badger-spring-boot.git