SpringBoot整合Swagger2 API文档

╰半橙微兮° 2024-04-23 20:07 108阅读 0赞

#### 概述 ####

前后端分离开发模式中，api 文档是最好的沟通方式。Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。具有及时性 (接口变更后，能够及时准确地通知相关前后端开发人员)，规范性 (并且保证接口的规范性，如接口的地址，请求方式，参数及响应格式和错误信息)，一致性 (接口信息一致，不会出现因开发人员拿到的文档版本不一致，而出现分歧)，可测性 (直接在接口文档上进行测试，以方便理解业务) 的特点。

#### 配置Swagger2 ####

1.  引入依赖

<dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
        </dependency>

1.  写配置类,可以直接使用下面的配置

import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import springfox.documentation.builders.ApiInfoBuilder;
    import springfox.documentation.service.ApiInfo;
    import springfox.documentation.service.Contact;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
    
    
    @Configuration
    @EnableSwagger2
    public class Swagger2Config {
        
        @Bean
        public Docket webApiConfig(){
        
            return new Docket(DocumentationType.SWAGGER_2)
                    .groupName("webApi")
                    .apiInfo(webApiInfo())
                    .select()
                    //只显示api路径下的页面
                    //.paths(Predicates.and(PathSelectors.regex("/api/.*")))
                    .build();
        }
    
        private ApiInfo webApiInfo(){
        
            return new ApiInfoBuilder()
                    .title("网站-API文档")
                    .description("本文档描述了网站微服务接口定义")
                    .version("1.0")
                    .contact(new Contact("xg", "http://xg.com", "2218877219@qq.com"))
                    .build();
        }
    }

1.  测试，启动Spring Boot主程序，访问：http://localhost:端口号/swagger-ui.html，端口号是自己项目设置的端口号。  
    ![在这里插入图片描述][15d9b86b69ca44ddad559da42a8804af.png]  
    ![在这里插入图片描述][d0b52f3f776b4eccb97600711f2ef92c.png]  
    **Try it out–>Execute**  
    ![在这里插入图片描述][45d886bca92e463da5316c297f1c404e.png]  
    ![在这里插入图片描述][1ec3a0fcc6f449c4ac3dbe8fe26933fe.png]
2.  测试结果：  
    ![在这里插入图片描述][2846e1ec688b45a2bb61133e50f40465.png]
3.  Swagger 使用的常用注解及其说明：
    
    @Api：用在类上，说明该类的作用。
    
    @ApiOperation：用在方法上,给API增加方法说明。
    
    @ApiParam，@ApiImplicitParams，@ApiImplicitParam：用在参数上,给API参数增加说明。
    
    @ApiModel 和 @ApiModelProperty主要是作用到实体类上，当接口中有一个方法的返回值为该对象时，就会在文档的model中显示该类的信息
    
    @ApiIgnore：用来排除不需要的接口信息

@Api(tags = "老师管理接口")
    @RestController
    @RequestMapping(value="/admin/teacher")
    public class TeacherController {
        
    
        @Autowired
        private TeacherService teacherService;
    
        //删除老师
        @ApiOperation("逻辑删除老师")
        @DeleteMapping("{id}")
        public boolean removeById(@ApiParam(name = "id", value = "老师ID", required = true) @PathVariable String id){
        
            return teacherService.removeById(id);
        }
    
        //查询所有老师列表
        @ApiOperation("所有老师列表")
        @GetMapping("findAll")
        public List<Teacher> findAll(){
        
            List<Teacher> list = teacherService.list();
            return list;
        }
    }

1.  补充说明：  
    如果项目中整合了Security，需要在其配置文件中将swagger的访问放行。

@Override
    
    public void configure(WebSecurity web) throws Exception {
        
    	web.ignoring()
    	.antMatchers("/swagger-ui.html")
    	.antMatchers("/v2/**")
    	.antMatchers("/swagger-resources/**");
    }

[15d9b86b69ca44ddad559da42a8804af.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/23/dce5f7ca1ec547a39dacf3a6f60fccd9.png
[d0b52f3f776b4eccb97600711f2ef92c.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/23/ac3c8c40170e493dad32a103de9f4d80.png
[45d886bca92e463da5316c297f1c404e.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/23/450002b2e0594210823a18c19c4b8ea3.png
[1ec3a0fcc6f449c4ac3dbe8fe26933fe.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/23/f6a6b918b21544ff91bb3df00d4a2fad.png
[2846e1ec688b45a2bb61133e50f40465.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/23/7366280fe6444fad87d9095e0ef9bdff.png