Swagger-Api超详细教程

此笔的博客

已于 2023-12-12 10:26:55 修改

阅读量1.3k

点赞数 17

文章标签： java 文心一言

于 2023-12-12 10:14:14 首次发布

本文链接：https://blog.csdn.net/2301_77112535/article/details/134942329

版权

接口文档是什么:

1、人为解释:

在项目开发中，web项目的前后端分离开发，APP开发，需要由前后端工程师共同定义接口，编写接口文档，之后大家都根据这个接口文档进行开发，到项目结束前都要一直维护。

二、为什么要写接口文档？

1、项目开发过程中前后端工程师有一个统一的文件进行沟通交流开发

2、项目维护中或者项目人员更迭，方便后期人员查看、维护

三、接口规范是什么？

首先接口分为四部分：方法、 uri、请求参数、返回参数

1、方法:新增(post) 修改(put) 删除(delete) 获取(get)

2、uri：以/a开头，如果需要登录才能调用的接口(如新增、修改；前台的用户个人信息，资金信息等)后面需要加/u，即：/a/u；中间一般放表名或者能表达这个接口的单词；get方法，如果是后台通过搜索查询列表，那么以/search结尾，如果是前台的查询列表，以/list结尾； url参数就不说了。

3、请求参数和返回参数，都分为5列：字段、说明、类型、备注、是否必填

字段是类的属性；说明是中文释义；类型是属性类型，只有String、Number、Object、Array四种类型；备注是一些解释，或者可以写一下例子，比如负责json结构的情况，最好写上例子，好让前端能更好理解；是否必填是字段的是否必填。

4、返回参数结构有几种情况：1、如果只返回接口调用成功还是失败（如新增、删除、修改等），则只有一个结构体：code和message两个参数；2、如果要返回某些参数，则有两个结构体：1是code/mesage/data，2是data里写返回的参数,data是object类型；3、如果要返回列表，那么有三个结构体，1是code/mesage/data,data是object，里面放置page/size/total/totalPage/list 5个参数，其中list是Arrary类型，list里放object，object里是具体的参数。

注意：uri地址里不允许出现大写字母，如果是两个单词拼接，用/分开

示例：

请求地址：get /a/student/list

返回参数:

2、理解:

自己理解的话首先我列三点复杂的事情

1、前端人员的疑惑

如果没有接口文档的话前端人员看后端的访问路径就会比较麻烦，因为Web的最后是前后端分离

2、不好测试

每次测试都需要去打开PostMan去测试你的后端接口,而接口文档提供了更好的调试工具可以不用写路径调试你的网址

3、不便于理解

文档俗称便于理解的东西如果不写个文档告诉前端人员这是什么东西前端人员就不知道你的这个接口访问路劲是干什么的

接口文档的创建步骤

第一步:

首先去导入Maven依赖对应接口文档的

<!--        接口文档-->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>3.0.3</version>
        </dependency>
        <dependency>
            <groupId>org.apache.poi</groupId>
            <artifactId>poi-ooxml</artifactId>
            <version>4.1.2</version> <!-- 请确保所有相关依赖都使用相同的版本号 -->
        </dependency>

导入了依赖之后

第二步:

去yml中配置

spring: 
  mvc: 
    pathmatch: 
       matching-strategy: ant_path_matcher

配这个有什么用:

默认情况下，Spring MVC 使用的是 AntPathMatcher 路径匹配策略，它是基于 Ant 风格的路径模式匹配器。Ant 风格的路径模式允许使用通配符（如 * 和 ?）来匹配路径的一部分或整个路径。

通过使用 AntPathMatcher，你可以在 Spring MVC 框架中使用类似 Ant 风格的路径模式来匹配请求的 URL 路径。这样可以方便地进行路径的模糊匹配、通配符匹配等操作，从而灵活地处理请求。

将 spring.mvc.pathmatch.matching-strategy 设置为 ant_path_matcher 是为了明确告知 Spring MVC 框架使用 AntPathMatcher 路径匹配策略。这样配置后，Spring MVC 将会使用 Ant 风格的路径模式匹配请求 URL 路径。

自我理解:

我觉得配置了这个就可以完全准确的扫描路劲了, 因为到最后是要展示文档的调试的时候要给对应的URL地址发送东西所以配置了这个可以准确的发送东西!

第三步:

然后去配置一下它的本类(就是它的配置)

@Configuration
@EnableKnife4j
@EnableSwagger2
public class SwaggerConfig {
    @Bean(value = "demoAPI")
    public Docket defaultApi2() {
        Docket docket = new Docket(DocumentationType.OAS_30).
                apiInfo(new ApiInfoBuilder().title("商品管理系统")
                        .description("# 这里记录服务端所有接口的入参,出参等等信息")
                        .termsOfServiceUrl("http://yaomaoyang.com")
                        .contact(new Contact("liangpengb", "http://127.0.0.1", "1781361090@QQ.com")).version("3.0").build())
                .groupName(Docket.DEFAULT_GROUP_NAME)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.controller")).paths(PathSelectors.any()).build();
        return docket;
    }

@EnableSwagger2解释:

@EnableSwagger2 是一个用于在 Spring Boot 中集成 Swagger2 的注解。Swagger2 是一个用于生成 API 文档的工具，它可以根据 API 接口的注解信息自动生成文档，并提供了一套交互式的 UI 界面，供开发人员查看和测试接口。通过使用 @EnableSwagger2 注解，可以在 Spring Boot 项目中启用 Swagger2，从而方便地生成、查看和测试 API 文档。

@EnableKnife4j解释:

@EnableKnife4j 是一个用于在 Spring Boot 中集成 Knife4j（原 Swagger-Bootstrap-UI）的注解。Knife4j 是一个增强版的 Swagger 文档生成工具，它能够生成美观、丰富的 API 文档，并提供交互式的接口测试功能。通过使用 @EnableKnife4j 注解，可以在 Spring Boot 项目中轻松地集成 Knife4j，从而简化 API 文档的生成和管理过程。

重写一下

改成自己的主页设计

第四步:

然后就可以给你的Controller层或者是别的层写了写注解完成最后的展示

@Api("") : 解释你的这个类是干什么用的

@ @ApiOperation ( " " ) 在访问接口上加的路劲解释你的这个接口访问是干什么用的

@ApiParme("") 在参数上加的东西解释你的这个参数是干什么用的

如果是实体类的参数

则在实体类中添加

@ApiMethod("") : 解释这个实体类是什么

@ApiModelProperty ( " " ) 解释你的这个全局变量是干什么用的!

第五步:

就可以直接去完成启动然后访问/doc.html啦