Spring Boot集成Swagger

于 2023-09-07 12:48:03 发布
阅读量357 收藏
点赞数 1
文章标签： spring boot java 后端 idea
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.youkuaiyun.com/weixin_52572813/article/details/132724419
版权

目录

概述

一、Swagger

1. Swagger的作用

2. Swagger的优点

二、Spring Boot集成Swagger

2.1 初始实现步骤

2.2 配置Swagger 

三、常用注解

概述

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的web服务的接口文档。目前的项目基本都是前后端分离，后端为前端提供接口的同时，还需同时提供接口的说明文档。但我们的代码总是会根据实际情况来实时更新，这个时候有可能会忘记更新接口的说明文档，造成一些不必要的问题。

一、Swagger

1. Swagger的作用

根据在代码中使用自定义的注解来生成接口文档，这个在前后端分离的项目中很重要。这样做的好处是 在开发接口时可以通过swagger 将接口文档定义好，同时也方便以后的维护。

2. Swagger的优点

（1）Swagger是一种流行的软件框架，帮助开发人员设计、构建、文档化和使用RESTful API。它提供了一组工具和库，使开发人员能够以直接易于使用的方式设计、构建、文档化和测试API。

（2）Swagger基于OpenAPI规范（OAS），这是一种描述和文档化API的标准。 OAS为指定API的结构和内容（包括其端点、操作、参数和响应）定义了一组规则和约定。通过遵循这些约定，开发人员可以创建API的机器可读描述，该描述可用于生成文档、测试用例和客户端代码。

（3）Swagger的一个关键优点是能够自动生成API文档。 Swagger提供了一个用户界面，使开发人员可以与API交互并实时查看响应。这使得开发人员很容易理解API如何工作并如何使用它。

（4）Swagger还可以用于为不同的编程语言生成客户端代码。这使得开发人员能够轻松地使用API并将其集成到自己的应用程序中。

（5）Swagger还包括许多用于测试和调试API的工具。它包括用于运行API请求的命令行工具和用于在浏览器中测试和调试API的基于Web的工具。

二、Spring Boot集成Swagger

2.1 初始实现步骤

1. 添加Maven依赖

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

2.编写HelloController类，测试确保运行成功

@RestController
public class HelloController {

    @RequestMapping("/hello")
    public String hello(){
        return "Hello World！";
    }
}

浏览器测试运行：

3. 编写一个配置类SwaggerConfig类来配置Swagger

@Configuration //配置类
@EnableSwagger2// 开启Swagger2的自动配置
public class SwaggerConfig {  
    
}

4. 访问测试：http://localhost:8080/swagger-ui.html，可以看到swagger的界面

注意：

如果启动报错空指针是因为springboot2.6.0中将SpringMVC默认路径匹配策略从AntPathMatcher 更改为PathPatternParser，导致出错。可以在启动类上加上@EnableWebMvc注解或者在配置文件中切换为原先的AntPathMatcher。

#原先的AntPathMatcher
spring.mvc.pathmatch.matching-strategy=ant_path_matcher
2.2 配置Swagger 

1. Swagger实例Bean是Docket，所以通过配置Docket实例来配置Swagger

@Bean //配置docket以配置Swagger具体参数
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2);
}

2. 可以通过apiInfo()属性配置文档信息

//配置文档信息
private ApiInfo apiInfo() {
        Contact contact = new Contact("联系人名字", "http://xxxxx.com/联系人访问链接", "联系人邮箱");
        return new ApiInfo(
                "Swagger学习", // 标题
                "学习演示如何配置Swagger", // 描述
                "v1.0", // 版本
                "http://xxxxx.com", // 组织链接
                contact, // 联系人信息
                "Apach 2.0 许可", // 许可
                "许可链接", // 许可连接
                new ArrayList<>()// 扩展
        );
}

3. Docket 实例关联上 apiInfo()

@Bean
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
}

4. 通过select()方法配置包路径来扫描接口

@Bean
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(apiInfo())
      .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
      .apis(RequestHandlerSelectors.basePackage("com.apesource.swagger.controller"))
      .build();
}

5. 配置接口扫描过滤

@Bean
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(apiInfo())
      .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
      .apis(RequestHandlerSelectors.basePackage("com.apesource.swagger.controller"))
       // 配置如何通过path过滤,即这里只扫描请求以/apesource开头的接口
      .paths(PathSelectors.ant("/apesource/**"))
      .build();
}

6. 配置API分组

如果没有配置分组，默认是default。通过groupName()方法即可配置分组。

@Bean
public Docket docket(Environment environment) {
   return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
      .groupName("hello") // 配置分组
       // 省略配置....
}

7. 配置多个分组

配置多个分组只需要配置多个docket即可。

Bean
public Docket docket1(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("group1");
}
@Bean
public Docket docket2(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("group2");
}
@Bean
public Docket docket3(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("group3");
}

SwaggerConfig配置类完整代码：

@Configuration
@EnableSwagger2
public class Swagger {

    @Bean
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("group1");
    }
    @Bean
    public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("group2");
    }
    @Bean
    public Docket docket3(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("group3");
    }
    
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("dytx").apiInfo(apiInfo())
                .select().apis(RequestHandlerSelectors.basePackage("com.dytx.springboot_swagger01.controller"))
                .build();
    }

    //配置文档信息
    private ApiInfo apiInfo() {
        Contact contact = new Contact("联系人名字", "http://xxxxx.com/联系人访问链接", "联系人邮箱");
        return new ApiInfo(
                "Swagger学习", // 标题
                "学习演示如何配置Swagger", // 描述
                "v2.0", // 版本
                "http://xxxxx.com", // 组织链接
                contact, // 联系人信息
                "Apach 2.0 许可", // 许可
                "许可链接", // 许可连接
                new ArrayList<>()// 扩展
        );
    }
}

访问测试：http://localhost:8080/swagger-ui.html，可以看到swagger的界面 

三、常用注解

（1）@Api：修饰整个类，描述Controller的作用。

语法：@Api(tags="说明该类的作用，可以在UI界面上看到的注解"，value = "/类的访问路径", description = "类的文字描述")

（2）@ApiOperation：描述一个类的一个方法，说明方法的作用。

语法：@ApiOperation(value = “接口说明”, httpMethod = “接口请求方式”, response = “接口返回参数类型”, notes = “接口发布说明”）

（3）@ApiImplicitParam**：一个请求参数。

语法：@ApiImplicitParam(required = “是否必须参数”, name = “参数名称”, value = “参数具体描述”,dateType="变量类型”,paramType="请求方式”)

（4）@ApiImplicitParams：用在请求的方法上，包含一组参数说明；

         @ApiImplicitParam：用在 @ApiImplicitParams注解中，指定一个请求参数的配置信息 。     
                name：参数名
                value：参数的汉字说明、解释
                required：参数是否必须传
                paramType：参数放在哪个地方
                    · header --> 请求参数的获取：@RequestHeader
                    · query --> 请求参数的获取：@RequestParam
                    · path（用于restful接口）--> 请求参数的获取：@PathVariable
                    · body（不常用）
                    · form（不常用）    
                dataType：参数类型，默认String，其它值dataType="Integer"       
                defaultValue：参数的默认值

示例：


@ApiImplicitParams({
    @ApiImplicitParam(name="phoneNumber",value="手机号码",required=true,paramType="form"),
    @ApiImplicitParam(name="password",value="密码",required=true,paramType="form"),
    @ApiImplicitParam(name="age",value="年龄",required=true,paramType="form",dataType="int")
})

（5）@ApiResponses：用于请求的方法上，表示一组响应；
         @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
                code：数字，例如400
                message：信息，例如"请求参数没填好"
                response：抛出异常的类

示例：


@ApiOperation(value = "select请求",notes = "多个参数，多种的查询参数类型")
@ApiResponses({
    @ApiResponse(code=400,message="请求参数错误"),
    @ApiResponse(code=404,message="请求路径没有或页面跳转路径找不到")
})
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值