Swagger使用教程

简介: Swagger使用教程

Swaggerj使用教程

简介

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

什么是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文件中添加以下依赖:
<!--引入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>
  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仓库中:博客中的代码

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的各项参数

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

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

这里面加上了对应的注释

ApiOperation和Api

接口测试

Swagger也是可以进行接口测试的

相关文章
|
8月前
|
移动开发 Java API
微服务技术系列教程(26) - SpringCloud- 接口管理Swagger
微服务技术系列教程(26) - SpringCloud- 接口管理Swagger
119 0
|
Java API Spring
Spring Boot 2.x基础教程:Swagger接口分类与各元素排序问题详解
特别开一篇详细说说Swagger中文档内容如何来组织以及其中各个元素如何控制前后顺序的具体配置方法。
3301 0
|
2月前
|
Dubbo Java 测试技术
提升API文档品质:Swagger annotations (注解)使用教程
Swagger 提供的注解集是其框架中定义 API 规范和文档的重要工具。这些注解在代码里标注重要部分,为 Swagger 的解析工作铺路,进而生成详尽的 API 文档。开发者编写的注释能够被转换成直观的文档,并展现API端点、参数和响应等信息。这不仅提升了开发人员对 API 运作的理解与沟通,也使得测试和集成过程更加顺畅。
|
8月前
|
Java API Maven
微服务技术系列教程(27) - SpringCloud- Zuul整合Swagger管理微服务所有API
微服务技术系列教程(27) - SpringCloud- Zuul整合Swagger管理微服务所有API
69 0
|
2月前
|
Java Maven
【SpringBoot专题_02】springboot集成Swagger详细教程
【SpringBoot专题_02】springboot集成Swagger详细教程
44 0
|
存储 SQL Java
Spring Boot + vue-element 开发个人博客项目实战教程(十、调试、密码加密和Swagger接口文档)(上)
Spring Boot + vue-element 开发个人博客项目实战教程(十、调试、密码加密和Swagger接口文档)(上)
75 1
|
前端开发 数据可视化 安全
Spring Boot + vue-element 开发个人博客项目实战教程(十、调试、密码加密和Swagger接口文档)(下)
Spring Boot + vue-element 开发个人博客项目实战教程(十、调试、密码加密和Swagger接口文档)(下)
142 0
|
前端开发 Java API
SpringBoot2.x系列教程13--SpringBoot中整合Swagger生成接口的在线文档
前言 在前一章节中,壹哥 带大家学习了如何基于RESTful来设计我们的Web接口,后端团队把接口设计出来了,前端团队就可以直接调用了吗?这里我们想一下,前端团队怎么知道后端团队设计的接口长啥样呢?前端调用接口时,该传递什么样的参数?返回值什么含义?接口地址在哪?......这些信息前端团队统统不知道啊,因为接口是后端写的! 所以前后端之间在进行接口调用时,是不是还需要有个可以展示暴露接口的东西呢?这就是接口文档了! 今天 壹哥 就带大家学习一个比较牛逼的在线接口文档工具--Swagger! 一. Swagger2简介 我们可以在Spring Boot中构建RESTful风格的API接口,
160 0
|
API
【Nest教程】集成Swagger自动生成接口文档
【Nest教程】集成Swagger自动生成接口文档
408 0
【Nest教程】集成Swagger自动生成接口文档
|
Java API Apache
Spring Boot 基础教程:使用 Swagger3 生成 API 接口文档
主要介绍如何使用 Spring Boot 集成 Swagger3,构建我们自己的 API 接口文档,并对比了 Swagger2 和 Swagger3 的区别,让我们从 Swagger2 向 Swagger3 过渡更加顺滑。
5628 0
Spring Boot 基础教程:使用 Swagger3 生成 API 接口文档