Spring Boot整合Swagger教程

电玩女神 2023-10-04 11:12 15阅读 0赞

## Swagger ##

#### 介绍 ####

*  Swagger是一款REST APIs文档生成工具。
 *  Swagger官方定义：Swagger是一款开源工具，依据OpenAPI规范（OpenAPI Specification，简称OAS）可以帮助你设计，构建，生成文档，消费（调用）REST APIs。主要的工具包含：
 *  Swagger Editor：基于web的一个工具，用于编写符合OpenAPI规范的模型
 *  Swagger UI：用于展示REST APIs文档，并提供一些交互操作
 *  Swagger Codegen： 依据OpenAPI规范来生成服务端和客户端代码

#### 优点 ####

*  通过代码和注释自动生成文档。在Swagger框架下，开发人员可对服务进行归类说明，对方法，模型，返回结果等进行详细说明。方便开发人员在编写代码的同时，编写文档信息。自动生成，只需很少的编辑工作，就能获得完整的REST APIs文档
 *  提供了UI界面。既展示接口信息，又提供了参数校验，测试功能
 *  形成了文档规范，支持不同的语言
 *  提供丰富的组件。

## SpringBoot+Swagger集成 ##

#### 使用官方依赖 ####

*  在pom.xml文件中添加Swagger相关依赖

<dependency>
    	<groupId>io.springfox</groupId>
    	<artifactId>springfox-swagger2</artifactId>
    	<version>2.9.2</version>
    </dependency>
    
    
    
    <dependency>
    	<groupId>io.springfox</groupId>
    	<artifactId>springfox-swagger-ui</artifactId>
    	<version>2.9.2</version>
    </dependency>
    
    
    
    <dependency>
    	<groupId>org.codehaus.jackson</groupId>
    	<artifactId>jackson-core-asl</artifactId>
    	<version>1.9.13</version>
    </dependency>```

#### 配置Swagger ####

*  要使用Swagger，我们必须对Swagger进行配置，我们需要创建一个Swagger的配置类，比如可以命名为`SwaggerConfig.java`

package com.dduan.common;
    
    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
    import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
    import springfox.documentation.builders.ApiInfoBuilder;
    import springfox.documentation.builders.PathSelectors;
    import springfox.documentation.builders.RequestHandlerSelectors;
    import springfox.documentation.service.ApiInfo;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
    
    @Configuration //标明是配置类
    @EnableSwagger2 //开启swagger功能
    public class SwaggerConfig implements WebMvcConfigurer {
        
        @Bean
        public Docket createRestApi() {
        
            return new Docket(DocumentationType.SWAGGER_2)  //DocumentationType.SWAGGER_2 固定的，代表swagger2
                    //.groupName("分布式任务系统") //如果配置多个文档的时候，那么需要配置groupName来分组标识
                    .apiInfo(apiInfo()) //用于生成API信息
                    .select() //select()函数返回一个ApiSelectorBuilder实例,用来控制接口被swagger做成文档
                    .apis(RequestHandlerSelectors.basePackage("com.dduan.controller")) //用于指定扫描哪个包下的接口
                    .paths(PathSelectors.regex(".sys/login"))//选择所有的API,如果你想只为部分API生成文档，可以配置这里
                    .build();
        }
    
        /**
         * 用于定义API主界面的信息，比如可以声明所有的API的总标题、描述、版本
         *
         * @return
         */
        private ApiInfo apiInfo() {
        
            return new ApiInfoBuilder()
                    .title("XX项目API") //可以用来自定义API的主标题
                    .description("XX项目SwaggerAPI管理") //可以用来描述整体的API
                    .termsOfServiceUrl("") //用于定义服务的域名
                    .version("1.0") //可以用来定义版本。
                    .build();
        }
    
        /**
         * swagger-ui.html访问不了，页面报错404,解决办法
         *
         * @param registry 注意：重写 addResourceHandlers 方法需要 implements WebMvcConfigurer 类
         */
        @Override
        public void addResourceHandlers(ResourceHandlerRegistry registry) {
        
    
            registry
                    .addResourceHandler("swagger-ui.html")
                    .addResourceLocations("classpath:/META-INF/resources/");
    
            registry
                    .addResourceHandler("/webjars/**")
                    .addResourceLocations("classpath:/META-INF/resources/webjars/");
        }
    }

#### 场景 ####

*  **@Api** 定义接口组

@Api(tags = "用户管理")
    @RestController
    @RequestMapping("/sys")
    public class UserController {
        
    }

*  **@ApiOperation** 定义接口

@Api(tags = "用户管理")
    @RestController
    @RequestMapping("/sys")
    public class UserController {
        
    	@ApiOperation(value = "用户登录")
        @RequestMapping(value = "/login", method = RequestMethod.POST, consumes = MediaType.APPLICATION_JSON_VALUE)
        public Resp login(@RequestBody LoginVo loginVo) {
        
        }
    }

#### 接口文档展示 ####

*  访问地址：`localhost:端口号/swagger-ui.html`
 *  API doc 页面及功能介绍  
    ![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2dpdGh1Yl8zODMzNjkyNA_size_16_color_FFFFFF_t_70_pic_center]
 *  点击 **Try it out** 按钮页面  
    ![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2dpdGh1Yl8zODMzNjkyNA_size_16_color_FFFFFF_t_70_pic_center 1]

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2dpdGh1Yl8zODMzNjkyNA_size_16_color_FFFFFF_t_70_pic_center]: https://img-blog.csdnimg.cn/20210419131500371.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2dpdGh1Yl8zODMzNjkyNA==,size_16,color_FFFFFF,t_70#pic_center
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2dpdGh1Yl8zODMzNjkyNA_size_16_color_FFFFFF_t_70_pic_center 1]: https://img-blog.csdnimg.cn/20210419132249920.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2dpdGh1Yl8zODMzNjkyNA==,size_16,color_FFFFFF,t_70#pic_center