整合Swagger2

灰太狼 2024-03-26 12:37 65阅读 0赞

## 整合Swagger2 ##

### 1、Swagger介绍 ###

前后端分离开发模式中，api文档是最好的沟通方式。

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

1、及时性 (接口变更后，能够及时准确地通知相关前后端开发人员)

2、规范性 (并且保证接口的规范性，如接口的地址，请求方式，参数及响应格式和错误信息)

3、一致性 (接口信息一致，不会出现因开发人员拿到的文档版本不一致，而出现分歧)

4、可测性 (直接在接口文档上进行测试，以方便理解业务)

### 2、集成knife4j ###

文档地址：[https://doc.xiaominfo.com/][https_doc.xiaominfo.com]

knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案。

knife4j属于service模块公共资源，因此我们集成到service-uitl模块

#### 2.1 添加依赖 ####

<dependency>
        <groupId>com.github.xiaoymin</groupId>
        <artifactId>knife4j-spring-boot-starter</artifactId>
    </dependency>

#### 2.2 添加knife4j配置类 ####

import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import springfox.documentation.builders.ApiInfoBuilder;
    import springfox.documentation.builders.ParameterBuilder;
    import springfox.documentation.builders.PathSelectors;
    import springfox.documentation.builders.RequestHandlerSelectors;
    import springfox.documentation.schema.ModelRef;
    import springfox.documentation.service.ApiInfo;
    import springfox.documentation.service.Contact;
    import springfox.documentation.service.Parameter;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;
    
    import java.util.ArrayList;
    import java.util.List;
    
    /**
     * knife4j配置信息
     */
    @Configuration
    @EnableSwagger2WebMvc
    public class Knife4jConfig {
        
    
        @Bean
        public Docket adminApiConfig(){
        
            List<Parameter> pars = new ArrayList<>();
            ParameterBuilder tokenPar = new ParameterBuilder();
            tokenPar.name("token")
                    .description("用户token")
                    .defaultValue("")
                    .modelRef(new ModelRef("string"))
                    .parameterType("header")
                    .required(false)
                    .build();
            pars.add(tokenPar.build());
            //添加head参数end
    
            Docket adminApi = new Docket(DocumentationType.SWAGGER_2)
                    .groupName("adminApi")
                    .apiInfo(adminApiInfo())
                    .select()
                    //只显示admin路径下的页面
                    .apis(RequestHandlerSelectors.basePackage("org.pp"))
                    .paths(PathSelectors.regex("/admin/.*"))
                    .build()
                    .globalOperationParameters(pars);
            return adminApi;
        }
    
        private ApiInfo adminApiInfo(){
        
    
            return new ApiInfoBuilder()
                    .title("后台管理系统-API文档")
                    .description("本文档描述了后台管理系统微服务接口定义")
                    .version("1.0")
                    .contact(new Contact("pp", "http://pp.com", "supanpan199919@163.com"))
                    .build();
        }
    
    
    }

#### 2.3接口上添加注解 ####

package org.pp.system.controller;
    
    import io.swagger.annotations.Api;
    import io.swagger.annotations.ApiOperation;
    import org.pp.model.system.SysRole;
    import org.pp.system.service.SysRoleService;
    import org.springframework.beans.factory.annotation.Autowired;
    import org.springframework.web.bind.annotation.*;
    
    import java.util.List;
    
    /**
     * TODO
     *
     * @author ss_419
     * @version 1.0
     * @date 2023/2/22 10:23
     */
    @Api(tags = "admin————角色管理")
    @RestController
    @RequestMapping("/admin/system/sysRole")
    public class SysRoleController {
        
    
        @Autowired
        SysRoleService sysRoleService;
    
        /**
         * 查询所有接口
         * @return
         */
        @ApiOperation(value = "查询所有记录")
        @GetMapping("findAll")
        public List<SysRole> findAll(){
        
            return sysRoleService.list();
        }
        @ApiOperation(value = "逻辑删除接口")
        @DeleteMapping("remove/{id}")
        public boolean removeRole(@PathVariable Long id){
        
            return sysRoleService.removeById(id);
        }
    }

#### 2.4测试 ####

接口地址：http://localhost:8800/doc.html  
![在这里插入图片描述][03fb0f5a8a8248f1bdfdc13f0d5d8fab.png]

[https_doc.xiaominfo.com]: https://doc.xiaominfo.com/
[03fb0f5a8a8248f1bdfdc13f0d5d8fab.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/26/99ba85a829d24518a5ee503463b7c139.png