SpringBoot整合Swagger2实现在线生成接口文档

最新推荐文章于 2024-10-12 15:17:24 发布

断橋殘雪

最新推荐文章于 2024-10-12 15:17:24 发布

阅读量1.6k

点赞数

分类专栏： SpringBoot 文章标签： SpringBoot swagger2

本文链接：https://blog.csdn.net/qq_35620501/article/details/92223892

版权

SpringBoot 专栏收录该内容

13 篇文章 1 订阅

订阅专栏

源码获取

GitHub：https://github.com/291685399/springboot-learning/tree/master/springboot-swagger201

pom.xml文件添加依赖

<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>
<dependency>
   <groupId>repos.io.springfox</groupId>
   <artifactId>springfox-swagger2</artifactId>
   <version>2.7.0</version>
</dependency>

配置Swagger2

创建Swagger2Config配置文件

@Configuration
public class Swagger2Config {
   @Bean
   public Docket createRestApi() {
       return new Docket(DocumentationType.SWAGGER_2)
               .apiInfo(apiInfo())
               .select()
               .apis(RequestHandlerSelectors.basePackage("com.wyj.controller"))//包的路径
               .paths(PathSelectors.any())
               .build();
   }
   @Bean
   public ApiInfo apiInfo() {
       return new ApiInfoBuilder()
               .title("API文档")//接口文档主题
               .description("API网关接口")//地址
               .termsOfServiceUrl("www.baidu.com")//路径
               .version("1.0.0")//版本号
               .build();
   }
}

在启动类中添加注解用于开启Swagger2

@EnableSwagger2

在Controller接口上配置接口参数信息

例子一：

@ApiOperation("根据用户id查询用信息")
@ApiImplicitParams({
        @ApiImplicitParam(name = "id", value = "用户id", required = true, dataType = "int", paramType = "query")
})
@RequestMapping(value = "/findById", method = RequestMethod.GET)
public String findById(int id) {
    return "{'id':'1','username':'zhangsan','password':'123'}";
}

例子二：

@ApiOperation("根据用户名查询用信息")
@ApiImplicitParams({
        @ApiImplicitParam(name = "username", value = "用户名", required = true, dataType = "String", paramType = "query")
})
@RequestMapping(value = "/findByUserName", method = RequestMethod.POST)
public String findByUsername(String username) {
    return "{'id':'2','username':'lisi','password':'456'}";
}

访问Swagger2

浏览器输入：http://127.0.0.1:8080/swagger-ui.html
在这里插入图片描述
点击demo-controller（这是上面两个例子的类名）张开

点击接口，查看接口详细信息

在Swagger2中可以在线调用接口，填写好需要的参数，点击Try it out即可（我这里findById这个接口id这个参数是请求中必须有的，在注解@ApiImplicitParam中已经定义了required = true）
在这里插入图片描述

最后，加上Swagger2常用注解说明：

@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个单数描述
@ApiModel：用对象来接收参数
@ApiProperty：用对象接收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中一个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError：发生错误返回的信息
@ApiImplicitParam：一个请求参数
@ApiImplicitParams：多个请求参数