SpringBoot集成Swagger2生成接口文档的方法示例

我们提供Restful接口的时候,API文档是尤为的重要,它承载着对接口的定义,描述等。它还是和API消费方沟通的重要工具。在实际情况中由于接口和文档存放的位置不同,我们很难及时的去维护文档。个人在实际的工作中就遇到过很多接口更新了很久,但是文档却还是老版本的情况,其实在这个时候这份文档就已经失去了它存在的意义。而 Swagger 是目前我见过的最好的API文档生成工具,使用起来也很方便,还可以直接调试我们的API。我们今天就来看下 Swagger2SpringBoot 的结合。

准备工作

一个SpringBoot项目,可以直接去官网 生成一个demo

一个用户类。

package cn.itweknow.springbootswagger.model;

import java.io.Serializable;

/**
 * @author ganchaoyang
 * @date 2018/12/19 10:29
 * @description
 */
public class User implements Serializable {

 private Integer id;

 private String name;

 private String password;

 private String email;
}

项目依赖

Web Service肯定是一个Web项目,所以我们这里依赖了 spring-boot-starter-web 包,其他两个包就是和 Swagger 相关的包了。

<dependency>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-starter-web</artifactId>
</dependency>

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

Swagger配置

Springfox Docket实例为Swagger配置提供了便捷的配置方法以及合理的默认配置。我们将通过创建一个Docket实例来对Swagger进行配置,具体配置如下所示。

@Configuration
@EnableSwagger2
public class SwaggerConfig extends WebMvcConfigurationSupport {

 @Bean
 public Docket productApi() {
  return new Docket(DocumentationType.SWAGGER_2).select()
    // 扫描的包路径
    .apis(RequestHandlerSelectors.basePackage("cn.itweknow.springbootswagger.controller"))
    // 定义要生成文档的Api的url路径规则
    .paths(PathSelectors.any())
    .build()
    // 设置swagger-ui.html页面上的一些元素信息。
    .apiInfo(metaData());
 }

 private ApiInfo metaData() {
  return new ApiInfoBuilder()
    // 标题
    .title("SpringBoot集成Swagger2")
    // 描述
    .description("这是一篇博客演示")
    // 文档版本
    .version("1.0.0")
    .license("Apache License Version 2.0")
    .licenseUrl("https://www.apache.org/licenses/LICENSE-2.0")
    .build();
 }

 @Override
 protected void addResourceHandlers(ResourceHandlerRegistry registry) {
  registry.addResourceHandler("swagger-ui.html")
    .addResourceLocations("classpath:/META-INF/resources/");

  registry.addResourceHandler("/webjars/**")
    .addResourceLocations("classpath:/META-INF/resources/webjars/");
 }
}

上述代码中的addResourceHandlers方法添加了两个资源处理程序,这段代码的主要作用是对Swagger UI的支持。

API文档

好了,到这一步,我们已经在一个SpringBoot项目中配置好了Swagger。现在,我们就来看一下如何去使用他。首先我们定义了一个 Controller 并提供了两个接口:

  • 通过用户id获取用户
  • 用户登录
@RestController
@RequestMapping("/user")
@Api(description = "用户相关接口")
public class UserController {

 /**
  * 通过id查询用户
  * @return
  */
 @RequestMapping(value = "/get", method = RequestMethod.GET)
 @ApiOperation("根据id获取用户")
 public User getUserById(@ApiParam(value = "用户id") Integer id) {
  return new User();
 }

 @RequestMapping(value = "/login", method = RequestMethod.POST)
 @ApiOperation("用户登录")
 public User login(@RequestBody User user) {
  return new User();
 }
}

相信大家都注意到了,这个 Controller 里面多了很多新的注解,比如说 @Api , @ApiOperation 等,下面我们就来一一解释一下。

  • @Api,这个注解是用在Controller类上面的,可以对Controller做必要的说明。
  • @ApiOperation,作用在具体的方法上,其实就是对一个具体的API的描述。
  • @ApiParam,对API参数的描述。

到这里,其实我们的Swagger就已经可以有效果了,让我们将项目运行起来先看看效果。访问 http://localhost:8080/swagger-ui.html 即可。

Model

在上面的图中可以看到在页面的下方有一个Models的标签,那么这个是啥呢。其实这个就是我们API中出现的一些对象的文档,我们也可以通过注解来对这些对象中的字段做一些说明,以方便使用者理解。以文章开头提到的 User 类来做一个说明。

@ApiModel("用户实体")
public class User implements Serializable {

 @ApiModelProperty(value = "用户id")
 private Integer id;

 @ApiModelProperty(value = "用户名称", required = true)
 private String name;

 @ApiModelProperty(value = "密码", required = true)
 private String password;

 @ApiModelProperty(value = "用户邮箱")
 private String email;
}

我们来看一下 User 类在Swagger上是如何展示的:

有一个细节,那就是required = true的字段上面被红星修饰,代表了必填项。

API测试

swagger-ui.html 页面上我们可以直接测试API,如下图所示,点击 Try it out ,然后填写参数,并点击 Execute 即可进行调用。

好了,对于Swagger的介绍就到这里了,最后奉上本文的源码地址, 请戳这里

以上就是本文的全部内容,希望对大家的学习有所帮助,也希望大家多多支持我们。

(0)

相关推荐

  • Spring Boot整合FTPClient线程池的实现示例

    最近在写一个FTP上传工具,用到了Apache的FTPClient,但是每个线程频繁的创建和销毁FTPClient对象对服务器的压力很大,因此,此处最好使用一个FTPClient连接池.仔细翻了一下Apache的api,发现它并没有一个FTPClientPool的实现,所以,不得不自己写一个FTPClientPool.下面就大体介绍一下开发连接池的整个过程,供大家参考. 我们可以利用Apache提供的common-pool包来协助我们开发连接池.而开发一个简单的对象池,仅需要实现common-p

  • 兼容Spring Boot 1.x和2.x配置类参数绑定的工具类SpringBootBindUtil

    为了让我提供的通用 Mapper 的 boot-starter 同时兼容 Spring Boot 1.x 和 2.x,增加了这么一个工具类. 在 Spring Boot 中,能够直接注入 XXProperties 类的地方不需要使用这个工具类. 但是在Spring 的接口和启动流程设计中,有些情况下只能通过EnvironmentAware接口得到Environment对象,此时你想得到 XXProperties 类没有更好的办法. 也许有人直接从Environment 对象中遍历获取所有的配置信

  • 详解Spring Boot中PATCH上传文件的问题

    Spring Boot中上传multipart/form-data文件只能是Post提交,而不针对PATCH,这个问题花了作者26个小时才解决这个问题,最后不得不调试Spring源代码来解决这个问题. 需求:在网页中构建一个表单,其中包含一个文本输入字段和一个用于文件上载的输入.很简单.这是表单: <form id="data" method="PATCH" action="/f" > <input type="tex

  • 详解Spring Boot2 Webflux的全局异常处理

    本文首先将会回顾Spring 5之前的SpringMVC异常处理机制,然后主要讲解Spring Boot 2 Webflux的全局异常处理机制. SpringMVC的异常处理 Spring 统一异常处理有 3 种方式,分别为: 使用 @ExceptionHandler 注解 实现 HandlerExceptionResolver 接口 使用 @controlleradvice 注解 使用 @ExceptionHandler 注解 用于局部方法捕获,与抛出异常的方法处于同一个Controller类

  • Spring Boot中优雅的获取yml文件工具类

    如何在spring boot中优雅的获取.yml文件工具类呢 代码如下: package com.common.base.utils.base; import com.common.base.generator.ResourceManager; import org.yaml.snakeyaml.Yaml; import java.io.InputStream; import java.util.HashMap; import java.util.Map; /** * yml文件工具类 */ p

  • spring boot结合Redis实现工具类的方法示例

    自己整理了 spring boot 结合 Redis 的工具类 引入依赖 <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-data-redis</artifactId> </dependency> 加入配置 # Redis数据库索引(默认为0) spring.redis.database=0 # Redis

  • 详解SpringBoot注入数据的方式

    关于注入数据说明 1.不通过配置文件注入数据 通过@Value将外部的值动态注入到Bean中,使用的情况有: 注入普通字符串 注入操作系统属性 注入表达式结果 注入其他Bean属性:注入Student对象的属性name 注入文件资源 注入URL资源 辅助代码 package com.hannpang.model; import org.springframework.beans.factory.annotation.Value; import org.springframework.stereo

  • Spring boot工具类静态属性注入及多环境配置详解

    由于需要访问MongoDB,但是本地开发环境不能直接连接MongoDB,需要通过SecureCRT使用127.0.0.2本地IP代理.但是程序部署到线上生产环境后,是可以直接访问MongoDB的,因此开发好程序后,总是要修改一下MongoDB服务器的IP才能提交代码,这样很是不方便. private static final String PUBCHAT_HOST = "127.0.0.2"; // private static final String PUBCHAT_HOST =

  • Docker部署Spring-boot项目的示例代码

    一.基础Spring-boot快速启动 1.1 快速启动 pom.xml加入如下依赖 <parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>2.0.5.RELEASE</version> </parent> <properties&g

  • Spring Boot配置拦截器及实现跨域访问的方法

    拦截器功能强大,能够深入方法前后,常应用于日志记录.权限检查和性能检测等,几乎是项目中不可或缺的一部分,本文就来实现Spring Boot自定义拦截器的配置. 理论指导 问:Spring Boot怎么配置拦截器? 答:配置一个拦截器需要两步完成. 自定义拦截器,实现HandlerInterceptor这个接口.这个接口包括三个方法,preHandle是请求执行前执行的,postHandler是请求结束执行的,但只有preHandle方法返回true的时候才会执行,afterCompletion是

随机推荐