【Springboot】swagger后端接口文档

红太狼 2024-03-27 11:01 96阅读 0赞

## Swagger ##

作用

*  后端接口文档清晰，及时更新
 *  接口可以在线测试

参考资料

*  官网：https://swagger.io/

## Swagger2 ##

### swagger2和swagger3的区别 ###

https://blog.csdn.net/A2254536570/article/details/121767271  
https://blog.csdn.net/qq\_35425070/article/details/105347336

## Swagger3 ##

> 参考资料  
> https://blog.csdn.net/cenrc/article/details/119279683

引入依赖

<dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-boot-starter</artifactId>
                <version>3.0.0</version>
            </dependency>

> 注意springboot2.6启动报错  
> 解决方法：在配置文件中添加
> 
>     spring:
>      mvc:
>        pathmatch:
>        matching-strategy: ant_path_matcher
> 
> ![在这里插入图片描述][9762aa5975ba46a5a36e9710070ee2c4.png]

在浏览器输入  
http://localhost:项目端口号/swagger-ui/index.html  
即可看到api页面  
![在这里插入图片描述][08bc242356464a20b24a184f5dfe1bc3.png]  
![在这里插入图片描述][ce0c205baade47beb55521cbc6255178.png]

通过配置类修改文档UI的内容

> 也可以通过yml来配置

@Configuration
    public class swaggerConfig {
        
    
        @Bean
        Docket docket(){
        
            // 设置 swagger的版本
            return new Docket(DocumentationType.OAS_30)
                    // 选择生成接口文档
                    .select()
                    // 包所在的路径
                    .apis(RequestHandlerSelectors.basePackage("org.crc.swagger3.controller"))
                    // 当前包下所有接口都生成
                    .paths(PathSelectors.any())
                    .build()
                    // 接口文档初始化，也就是设置接口文档的详细信息，
                    .apiInfo(
                        new ApiInfoBuilder()
                            .description("xxx 项目接口文档")
                             // 联系人
                            .contact(new Contact("crc","https://blog.csdn.net/cenrc?spm=1001.2101.3001.5343","2516313840@qq.com"))
                            .version("v1.0")
                            .title("API 测试文档")
                            .license("Apache 2.0")
                            .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0")
                            .build()
                    );
        }
    }

> 一些扫描配置项  
> ![在这里插入图片描述][210199f8c65e475093c68391a68acf73.png]

修改后  
![在这里插入图片描述][25367a7fed154715b3e46259fe58e7d9.png]

> 只希望swagger在生产环境中使用，不在发布中使用？  
> 根据开发环境，给Docket().enable(false)或者enable(true)

#### API文档分组 ####

分组，如何多个分组？，我有多个docket就可以有多个.groupName

@Bean
        public GroupedOpenApi publicApi() {
        
            return GroupedOpenApi.builder()
                    .setGroup("springshop-public")
                    .pathsToMatch("/public/**")
                    .build();
        }
      
        @Bean
        public GroupedOpenApi adminApi() {
        
            return GroupedOpenApi.builder()
                    .setGroup("springshop-admin")
                    .pathsToMatch("/admin/**")
                    .build();
        }

配置多个组

就是有很多个docket，

效果：  
![5f20c75b64014e1fb6a7f6543c2f972f.png][]

### 注解 ###

> 参考资料  
> https://blog.csdn.net/qq\_35425070/article/details/105347336

![在这里插入图片描述][75d1923626d244cc85bd7d4d3a7e08e6.png]

#### 实体类相关 ####

api方法的返回值类型相关的实体类都会被扫描  
@Schema

> 注意要有set和get

public class Result {
        
        @Schema(description = "状态码")
        private Integer code;
        @Schema(description = "消息")
        private String message;
        @Schema(description = "数据")
        private Object data;

![在这里插入图片描述][97918ae7d7354075874e18d85e79f733.png]

#### 控制类相关 ####

@Operation（）用于方法  
等

> 注意value和description，一个注解可能有多个参数，表示为不同的形式

@Operation(description ="获取文件列表")
        @GetMapping("/fileList")
        public Result getFileList(){
        
            logger.info("查询文件列表");
            List<FilePO> fileList = fileService.selectFileList();
            return  new Result(201,"文件列表查询成功",fileList);
        }

![在这里插入图片描述][09779f73ae2845b28ab52cdf370218d9.png]

## 在线测试 ##

点击“try it out ”,输入相关参数，即可在线测试接口

![在这里插入图片描述][430af495b2c24b5caff92b29f721b850.png]

[9762aa5975ba46a5a36e9710070ee2c4.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/27/246a5b71ec264ab2b51936e0ae95f982.png
[08bc242356464a20b24a184f5dfe1bc3.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/27/6957357e689a494082d628cd028393e8.png
[ce0c205baade47beb55521cbc6255178.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/27/f8eaad63b165487682b33c44c63eff33.png
[210199f8c65e475093c68391a68acf73.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/27/a5404ec6fcfc445883adc97bf25d531a.png
[25367a7fed154715b3e46259fe58e7d9.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/27/40ff287269c24d979dcd80808eb517c1.png
[5f20c75b64014e1fb6a7f6543c2f972f.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/27/091a7453c96f490ba1a41d2e1b638003.png
[75d1923626d244cc85bd7d4d3a7e08e6.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/27/eb8ba42f99fd49e0a57aa23bab5a4aea.png
[97918ae7d7354075874e18d85e79f733.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/27/4e307b2084184e6ebc96c90ca0ff36a6.png
[09779f73ae2845b28ab52cdf370218d9.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/27/274d65c058f4424598bcce0c96122d02.png
[430af495b2c24b5caff92b29f721b850.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/27/a7158019d6dc468da1f59ec2b0d263e3.png