SpringBoot 集成Swagger3

水深无声 2023-10-10 13:39 6阅读 0赞

## 一，什么是swagger? ##

1, Swagger 是一个规范和完整的文档框架，

用于生成、描述、调用和可视化 RESTful 风格的 Web 服务文档

官方网站:https://swagger.io/

2，使用swagger要注意的地方:

在生产环境中必须关闭swagger,

它本身只用于前后端工程师之间的沟通,

可以专门使用一台内部服务器来展示ui供访问,

即使在这上面要做好安全措施

3, 因为swagger3.0.0已发布，本文使用了最新版

如果有还在用2.x版本的请参考时注意区分

## 二，SpringBoot 集成swagger3 ##

### pom.xml 集成Swagger3依赖 ###

<dependency>
    			<groupId>io.springfox</groupId>
    			<artifactId>springfox-boot-starter</artifactId>
    			<version>3.0.0</version>
    			<exclusions>
    				<exclusion>
    					<groupId>org.springframework.plugin</groupId>
    					<artifactId>spring-plugin-core</artifactId>
    				</exclusion>
    				<exclusion>
    					<groupId>org.springframework.plugin</groupId>
    					<artifactId>spring-plugin-metadata</artifactId>
    				</exclusion>
    			</exclusions>
    		</dependency>

### Swagger3 配置对象定义 ###

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.oas.annotations.EnableOpenApi;
    import springfox.documentation.service.ApiInfo;
    import springfox.documentation.service.Contact;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    
    @Configuration
    @EnableOpenApi
    public class Swagger3Config {
    	@Bean
        public Docket createRestApi() {
            return new Docket(DocumentationType.OAS_30)
                    .apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.digipower.controller"))
                    .paths(PathSelectors.any())
                    .build();
        }
    
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder().title("在奋斗的大道上 - 微信预约查档系统").termsOfServiceUrl("https://blog.csdn.net/zhouzhiwengang")
    				.description("API接口")
    				.contact(new Contact("https://blog.csdn.net/zhouzhiwengang","",""))
    				.version("3.0").build();
        }
    
    }

### SpringBoot 集成Swagger3 接口文档效果截图 ###

![watermark_type_d3F5LXplbmhlaQ_shadow_50_text_Q1NETiBA5Zyo5aWL5paX55qE5aSn6YGT_size_20_color_FFFFFF_t_70_g_se_x_16][]

### SpringBoot 访问Swagger3接口文档地址 ###

默认接口访问地址:[http://192.168.0.1:5988/swagger-ui/][http_192.168.0.1_5988_swagger-ui]

## 三，swagger3 注解标签使用 ##

@ApiModel用于类上面说明功能

@ApiModelProperty用于字段上说明功能

示列截图：

![watermark_type_d3F5LXplbmhlaQ_shadow_50_text_Q1NETiBA5Zyo5aWL5paX55qE5aSn6YGT_size_19_color_FFFFFF_t_70_g_se_x_16][]

@Api用来指定一个controller中的各个接口的通用说明

@ApiOperation用来说明一个方法

@ApiImplicitParams:用来包含多个包含多个 @ApiImplicitParam

@ApiImplicitParam:用来说明一个请求参数

示列截图：

![watermark_type_d3F5LXplbmhlaQ_shadow_50_text_Q1NETiBA5Zyo5aWL5paX55qE5aSn6YGT_size_20_color_FFFFFF_t_70_g_se_x_16 1][]

> 温馨提示：针对任何请求参数结构说明，请一定记得要添加@ApiParam 标签，如果不添加@ApiParam标签，在Swagger3文档中针对参数结构说明就是空

[watermark_type_d3F5LXplbmhlaQ_shadow_50_text_Q1NETiBA5Zyo5aWL5paX55qE5aSn6YGT_size_20_color_FFFFFF_t_70_g_se_x_16]: https://img-blog.csdnimg.cn/dc72bc869baf4eafb5fa771d07470c9f.png?x-oss-process=image/watermark,type_d3F5LXplbmhlaQ,shadow_50,text_Q1NETiBA5Zyo5aWL5paX55qE5aSn6YGT,size_20,color_FFFFFF,t_70,g_se,x_16
[http_192.168.0.1_5988_swagger-ui]: http://192.168.1.74:5098/swagger-ui/
[watermark_type_d3F5LXplbmhlaQ_shadow_50_text_Q1NETiBA5Zyo5aWL5paX55qE5aSn6YGT_size_19_color_FFFFFF_t_70_g_se_x_16]: https://img-blog.csdnimg.cn/7d7a4f9302f547d78c4b1eec3aaf782c.png?x-oss-process=image/watermark,type_d3F5LXplbmhlaQ,shadow_50,text_Q1NETiBA5Zyo5aWL5paX55qE5aSn6YGT,size_19,color_FFFFFF,t_70,g_se,x_16
[watermark_type_d3F5LXplbmhlaQ_shadow_50_text_Q1NETiBA5Zyo5aWL5paX55qE5aSn6YGT_size_20_color_FFFFFF_t_70_g_se_x_16 1]: https://img-blog.csdnimg.cn/e848fda86e334af6a397ebc1d25e1c90.png?x-oss-process=image/watermark,type_d3F5LXplbmhlaQ,shadow_50,text_Q1NETiBA5Zyo5aWL5paX55qE5aSn6YGT,size_20,color_FFFFFF,t_70,g_se,x_16