SpringBoot集成Swagger2构建接口文档

最新推荐文章于 2024-01-23 15:38:14 发布

原创最新推荐文章于 2024-01-23 15:38:14 发布 · 231 阅读

0 ·

CC 4.0 BY-SA版权

文章标签：

#Swagger2

框架专栏收录该内容

23 篇文章

订阅专栏

本文详细介绍Swagger2的使用方法，包括如何自动生成RESTful API文档，常用API注解介绍，以及SpringBoot环境下Swagger2的集成步骤。适用于快速上手并进行功能测试。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

Swagger官网：https://swagger.io/

参考博客：https://blog.youkuaiyun.com/sanyaoxu_2/article/details/80555328

https://blog.youkuaiyun.com/forezp/article/details/71023536

一、简介
Swagger是一款Restful接口的文档在线自动生成+功能测试的软件。

Swagger是一个规范和完整的框架。用于生成、描述、调用和可视化Restful风格的Web服务。总体目标是使客户端和文件系统

作为服务器以同样的速度来更新。文件的方法、参数和模型紧密集成到服务器端的代码，允许API来始终保持同步.

二、Swagger2常用api注解
   @Api：用在类上，说明该类的作用
   @ApiOperation：用在方法上，说明方法的作用
   @ApiImplicitParams：用在方法上包含一组参数说明
   @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
   paramType：参数放在哪个地方
   header–>请求参数的获取：@RequestHeader
   query–>请求参数的获取：@RequestParam
   path（用于restful接口）–>请求参数的获取：@PathVariable
   name：参数名
   dataType：参数类型
   required：参数是否必须传
   value：参数的意思
   defaultValue：参数的默认值
   @ApiResponses：用于表示一组响应
   @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息 code：数字，例如400 message：信息，例如”请求参数没填好”
   response：抛出异常的类
   @ApiModel：描述一个Model的信息（
   @ApiModelProperty：描述一个model的属性

三、使用步骤

1、添加pom依赖

<dependency>
           <groupId>io.springfox</groupId>
           <artifactId>springfox-swagger2</artifactId>
           <version>2.7.0</version>
       </dependency>
       <dependency>
           <groupId>io.springfox</groupId>
           <artifactId>springfox-swagger-ui</artifactId>
           <version>2.7.0</version>
       </dependency>

注意：guava的jar版本必须20以上，否则启动缺少相关jar依赖

2、新增Swagger的配置类

@Configuration
@EnableSwagger2 // 开启swagger2
public class SwaggerConfig {

   @Bean
   public Docket docket() {
       return new Docket(DocumentationType.SWAGGER_2)
               .produces(Sets.newHashSet("application/json"))
               .consumes(Sets.newHashSet("application/json"))
               .protocols(Sets.newHashSet("http", "https"))
               // 文档说明
               .apiInfo(apiInfo()).select()
               // 指定controller存放的目录路径
               .apis(RequestHandlerSelectors.basePackage("com.test.index.controller"))
               .paths(PathSelectors.any())
               .build();

}

   // 构建api文档的详细说明
   private ApiInfo apiInfo() {
       return new ApiInfoBuilder()
               // 文档标题
               .title("springBoot集成Swagger2构建RESTful API")
               // 创建人
               .contact(new Contact("test", "http://www.baidu.com", ""))
               // 版本号
               .version("1.0")
               // 文档描述
               .description("API 描述").build();
   }
}

3、新增swagger-ui.html的静态资源路径映射，解决访问swagger-ui.htm页面404问题

SpringBoot自动配置本身并不会把/swagger-ui.html这个路径映射到对应的目录META-INF/resources/下面，需要配置

@Configuration
public class WebMvcConfig extends WebMvcConfigurerAdapter {
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {

registry.addResourceHandler("swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");

registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}
4、查看文档：http://ip:端口/项目路径/swagger-ui.html