Swagger使用教程

GeekLiHua

发布于 2025-01-21 16:36:20

6100

代码可运行

文章被收录于专栏：JavaJava

运行总次数：0

代码可运行

Swaggerj使用教程

简介

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

什么是Swagger？

这里是Swagger的官网:Swagger官网

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

Swagger的主要功能包括：

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

Swagger的安装和配置

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

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

<!--引入swagger-->
<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>

配置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路径的匹配规则。

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

实践

文章中的项目在这个gitee仓库中:博客中的代码

Springboot集成Swagger

开启Swagger

@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);
    }

}

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

配置Swagger信息

Swagger的bean实例Docket

这是Swagger中的Docket的各项参数

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

@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());
    }

}

这个时候，这里的信息就发生了改变

配置扫描接口与开关

@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了

分组也接口注释

配置API分组

.groupName("极客李华")

配置多个分组

@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");
    }

现在就有了多个分组，可以看出来，每个分组的内容都不相同

接口注释

简介

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

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