Swagger使用教程

本是古典何须时尚 2024-03-24 22:40 19阅读 0赞

## Swaggerj使用教程 ##

### 简介 ###

Swagger是个非常强大的API文档工具，它们可以帮助开发人员快速创建和管理API文档，并提供了丰富的功能和可视化界面。本文将为您介绍Swagger和Knife4j的使用教程，帮助您更好地了解和使用它们。

#### 什么是Swagger？ ####

这里是Swagger的官网:[Swagger官网][Swagger]

Swagger是一个用于设计、构建、文档化和使用RESTful风格的Web服务的开源软件框架。它提供了一种简单而强大的方式来描述和访问API的功能，使得开发人员可以更轻松地构建和测试API。

Swagger的主要功能包括：

1.  API文档自动生成：Swagger可以根据代码注释自动生成API文档，包括API的路径、参数、请求和响应的格式等信息。
2.  可视化界面：Swagger提供了一个可视化的界面，使开发人员可以直观地查看和测试API。
3.  API测试工具：Swagger提供了一个内置的API测试工具，可以直接在文档中进行API的测试和调试。
4.  API验证：Swagger可以验证API的请求和响应的格式是否符合定义的规范。

*  Swagger的安装和配置

要使用Swagger，您需要将Swagger的库添加到您的项目中，并进行相应的配置。

1.  添加Swagger库：在Maven项目中，您可以在`pom.xml`文件中添加以下依赖：

<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>io.swagger</groupId>
        <artifactId>swagger-annotations</artifactId>
        <version>1.5.22</version>
    </dependency>
    <dependency>
        <groupId>io.swagger</groupId>
        <artifactId>swagger-models</artifactId>
        <version>1.5.22</version>
    </dependency>

1.  配置Swagger：在您的Spring Boot应用程序中，您需要创建一个配置类来启用Swagger和配置相关的参数。以下是一个示例配置类：

@Configuration
    @EnableSwagger2
    public class SwaggerConfig {
        
    
        @Bean
        public Docket api() {
        
            return new Docket(DocumentationType.SWAGGER_2)
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.example.api"))
                    .paths(PathSelectors.any())
                    .build();
        }
    }

在上述配置中，您需要指定API的包路径和URL路径的匹配规则。

1.  启动应用程序：完成上述配置后，您可以启动您的应用程序，并访问`http://localhost:8080/swagger-ui.html`来查看生成的API文档。

### 实践 ###

文章中的项目在这个gitee仓库中:[博客中的代码][Link 1]  
![在这里插入图片描述][9912b3dd5ce3445885e48721647e59ff.png]

#### Springboot集成Swagger ####

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

*  开启Swagger  
    ![在这里插入图片描述][5de3b39b2e9941c8ad1eca0dc889a9a2.png]

配置好了之后，就可以启动了。  
我配置的端口号是8080，然后打开这个地址就可以进入Swagger的页面：http://localhost:8080/swagger-ui.html

![在这里插入图片描述][3f8b7d5176c048daa4435a5a41e42512.png]

#### 配置Swagger信息 ####

*  Swagger的bean实例Docket

这是Swagger中的Docket的各项参数

1.  groupName(String)：指定API文档的分组名称。可以使用多个Docket实例来创建多个API文档分组，每个分组可以有不同的配置。
2.  select()：返回一个ApiSelectorBuilder对象，用于定义哪些接口和路径应该包含在生成的文档中。
    
     *  apis(Predicate)：用于筛选包含在文档中的接口。可以使用RequestHandlerSelectors类提供的一些静态方法来定义筛选规则，例如basePackage()、any()、none()等。
     *  paths(Predicate)：用于筛选包含在文档中的路径。可以使用PathSelectors类提供的一些静态方法来定义筛选规则，例如ant()、regex()等。
3.  apiInfo(ApiInfo)：用于设置API文档的基本信息，包括标题、描述、版本号、联系人信息等。
    
     *  title(String)：设置API文档的标题。
     *  description(String)：设置API文档的描述。
     *  version(String)：设置API文档的版本号。
     *  termsOfServiceUrl(String)：设置API文档的服务条款URL。
     *  license(License)：设置API文档的许可证信息，包括名称和URL。
     *  contact(Contact)：设置API文档的联系人信息，包括姓名、邮箱、网址等。
4.  protocols(Set)：设置API文档支持的协议。可以使用字符串集合指定多个协议，例如"http"、"https"等。
5.  host(String)：设置API文档的主机名。可以指定完整的主机名，例如"www.example.com"，或者只指定域名部分。
6.  pathMapping(String)：设置API文档的基础路径。可以指定一个路径前缀，用于对所有路径进行统一的处理。
7.  enable(boolean)：设置是否启用Swagger文档生成。默认情况下，Swagger文档生成是启用的。
8.  ignoredParameterTypes(Class<?>…)：设置要忽略的参数类型。在生成API文档时，将忽略指定类型的参数。
9.  globalOperationParameters(List)：设置全局的操作参数。这些参数将应用于所有的API操作。
10. additionalModels(Class<?>…)：设置额外的模型类。这些模型类将被包含在生成的API文档中。

![在这里插入图片描述][26483600b4834242b57ea03160390881.png]

@Configuration
    @EnableWebMvc
    @EnableSwagger2 // 开启Swagger2
    
    public class SwaggerConfig implements WebMvcConfigurer {
        
        @Override
        public void addResourceHandlers(ResourceHandlerRegistry registry) {
        
    
            registry.addResourceHandler("/**").addResourceLocations(
                    "classpath:/static/");
            registry.addResourceHandler("swagger-ui.html").addResourceLocations(
                    "classpath:/META-INF/resources/");
            registry.addResourceHandler("/webjars/**").addResourceLocations(
                    "classpath:/META-INF/resources/webjars/");
            WebMvcConfigurer.super.addResourceHandlers(registry);
        }
    
        @Bean
        public Docket docket(){
        
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo());
        }
    
        // 配置Swagger信息=apiInfo
        private ApiInfo apiInfo(){
        
            // 作者的信息
            Contact contact = new Contact("极客李华", "https://blog.csdn.net/qq_51447496?spm=1011.2415.3001.5343", "1369990609@qq.com");
            return new ApiInfo("极客李华的SwaggerAPI文档",
                    "Wonder OF U",
                    "V1.0",
                    "https://blog.csdn.net/qq_51447496?spm=1011.2415.3001.5343",
                    contact,
                    "Apache 2.0",
                    "http://www.apache.org/licenses/LICENSE-2.0.html",
                    new ArrayList());
        }
    
    }

这个时候，这里的信息就发生了改变  
![在这里插入图片描述][f4b739bc2e094c8daa6056b273db18d6.png]

#### 配置扫描接口与开关 ####

![在这里插入图片描述][46bfb76e91ae4790972a06286722e85a.png]

@Bean
        public Docket docket(){
        
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    // RequestHandlerSelectors 配置要扫描接口的方式
                    // basePackage
                    // any() 扫描全部
                    // none() 不扫描
                    // withClassAnnotation 扫描类上的注解，参数是一个注解的反射对象
                    // withMethodAnnotation 扫描方法上的注解，参数是一个注解的反射对象
                    .apis(RequestHandlerSelectors.basePackage("com.example.swaggerdemo.controller"))
                    // paths() 过滤什么路径
                    .paths(PathSelectors.ant("/user/**")) // 允许/user/下面所有的
                    .build();
        }

在上面的配置中，我们只允许user下面的包，这个时候，我们的接口文档里面就只有usercontroller了  
![在这里插入图片描述][b6199747cf6d48b19c956fa4f7d5322f.png]  
![在这里插入图片描述][1519dda80ce44e15b81ecaabd878df88.png]

#### 分组也接口注释 ####

##### 配置API分组 #####

`.groupName("极客李华")`

![在这里插入图片描述][8526d09565ef4db99a2d400f93f35b88.png]  
![在这里插入图片描述][b0f5db0e913044dbb1f929914eacbe73.png]

*  配置多个分组  
    ![在这里插入图片描述][a3e48c99dc1b4850964291332117d78a.png]

@Bean
        public Docket docket(){
        
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .groupName("极客李华")
                    .enable(true) // enable是否启动Swagger,如果为False 则无法访问Swagger
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.example.swaggerdemo.controller"))
                    .build();
        }
    
        @Bean
        public Docket docket1(){
        
            return new Docket(DocumentationType.SWAGGER_2).groupName("A");
        }
        @Bean
        public Docket docket2(){
        
            return new Docket(DocumentationType.SWAGGER_2).groupName("B");
        }
        @Bean
        public Docket docket3(){
        
            return new Docket(DocumentationType.SWAGGER_2).groupName("C");
        }

现在就有了多个分组，可以看出来，每个分组的内容都不相同  
![在这里插入图片描述][d5c46300a6a041b5ba64e8e01c3b56a8.png]

##### 接口注释 #####

###### 简介 ######

在Swagger中，有一些用于定义API文档的注解和语法，包括@ApiModel、@ApiModelProperty、@ApiParam等。下面是对这些注解和语法的详细介绍：

1.  @ApiModel：用于对数据模型进行注解，定义在类上。可以用来描述请求或响应中的数据模型。常用的属性有：
    
     *  value：指定数据模型的名称。
     *  description：指定数据模型的描述。
     *  parent：指定数据模型的父类。
     *  discriminator：指定数据模型的鉴别器属性。
2.  @ApiModelProperty：用于对数据模型的属性进行注解，定义在类的字段或方法上。可以用来描述属性的名称、类型、描述等信息。常用的属性有：
    
     *  value：指定属性的名称。
     *  dataType：指定属性的数据类型。
     *  required：指定属性是否必填。
     *  example：指定属性的示例值。
     *  notes：指定属性的描述。
     *  hidden：指定属性是否在文档中隐藏。
3.  @ApiParam：用于对方法的参数进行注解，定义在方法的参数上。可以用来描述参数的名称、类型、描述等信息。常用的属性有：
    
     *  value：指定参数的名称。
     *  required：指定参数是否必填。
     *  defaultValue：指定参数的默认值。
     *  allowableValues：指定参数的可选值范围。
     *  allowMultiple：指定参数是否允许多个值。
     *  access：指定参数的访问权限。
4.  @ApiOperation：用于对API操作进行注解，定义在方法上。可以用来描述API操作的名称、描述、请求方法等信息。常用的属性有：
    
     *  value：指定API操作的名称。
     *  notes：指定API操作的描述。
     *  httpMethod：指定API操作的请求方法。
     *  response：指定API操作的响应类型。
     *  consumes：指定API操作接受的媒体类型。
     *  produces：指定API操作返回的媒体类型。
     *  responseContainer：指定API操作的响应容器类型。

###### ApiModel和ApiModelProperty ######

![在这里插入图片描述][2fe27806d0224a0d8fda47c775834285.png]  
这里面加上了对应的注释  
![在这里插入图片描述][b35651514d40479c87c5610505b3ec7d.png]

###### ApiOperation和Api ######

![在这里插入图片描述][2acf6745da3f450f82e7900818c7ddde.png]

![在这里插入图片描述][780865f93db645af96a70735926a1567.png]  
![在这里插入图片描述][6b145fc4b2b74c93a3d80a59a2044b24.png]

###### 接口测试 ######

Swagger也是可以进行接口测试的  
![在这里插入图片描述][a13b544798964783bf5db3ea8f129389.png]  
![在这里插入图片描述][119586828443435aaf642021fdf0516b.png]  
![在这里插入图片描述][2fd99c8875464d64a7ff5a48b3f18165.png]

[Swagger]: https://swagger.io/
[Link 1]: https://gitee.com/geek-li-hua/code-in-blog.git
[9912b3dd5ce3445885e48721647e59ff.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/13/ce276d67649b450e92687151f3551966.png
[b7006f62f57e486b8afd8d1d95c74c86.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/13/ee5c4a601e44414ab3e275f99fd14c84.png
[5de3b39b2e9941c8ad1eca0dc889a9a2.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/13/f02a1e2c5c6b4669a9eda09c68c7d554.png
[3f8b7d5176c048daa4435a5a41e42512.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/13/6c6f514573644ac888d1d01609abd0e9.png
[26483600b4834242b57ea03160390881.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/13/bc9c48df6e3045cf8e8b3c49e7d25574.png
[f4b739bc2e094c8daa6056b273db18d6.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/13/46f28706c6ac4ddcb093c0a31bfd763e.png
[46bfb76e91ae4790972a06286722e85a.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/13/a3a1f294019f472bacd1492432408c8f.png
[b6199747cf6d48b19c956fa4f7d5322f.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/13/aab485d284044a29bf2f0947bbc4135e.png
[1519dda80ce44e15b81ecaabd878df88.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/13/92572fd8d7794cd1bfdef4c6542cb931.png
[8526d09565ef4db99a2d400f93f35b88.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/13/9a196b742cdd41bca23607477e2ff9f7.png
[b0f5db0e913044dbb1f929914eacbe73.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/13/a478b7278cce4a69acd5599e01a4f843.png
[a3e48c99dc1b4850964291332117d78a.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/13/56d7d9da5a9c4ce8a5b8374c9ecad8e7.png
[d5c46300a6a041b5ba64e8e01c3b56a8.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/13/b94da173570a450eb63f2d9ea9a01323.png
[2fe27806d0224a0d8fda47c775834285.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/13/b66b8078cea34977a7a05e79242cfa42.png
[b35651514d40479c87c5610505b3ec7d.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/13/9e4bdd9219994cb185d62f68b28aacce.png
[2acf6745da3f450f82e7900818c7ddde.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/13/a331017b279740de89bd54737c011fed.png
[780865f93db645af96a70735926a1567.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/13/466b5b4b36964fc38699ad0bebc93487.png
[6b145fc4b2b74c93a3d80a59a2044b24.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/13/0c7e249ce2644ee49260243d19683103.png
[a13b544798964783bf5db3ea8f129389.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/13/20de4a5f86aa4f849d4a1ac30f3bbc1a.png
[119586828443435aaf642021fdf0516b.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/13/1bf1de08c64544c69cb18c7accdaaf41.png
[2fd99c8875464d64a7ff5a48b3f18165.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/13/a58497fdf326449fa2e6e46a79095aa5.png