Spring Boot 使用 Swagger 构建 RestAPI 接口文档

源码地址:https://github.com/laolunsi/spring-boot-examples

目前SpringBoot常被用于开发Java Web应用,特别是前后端分离项目。为方便前后端开发人员进行沟通,我们在SpringBoot引入了Swagger。

Swagger作用于接口,让接口数据可视化,尤其适用于Restful APi

本节分两部分介绍,第一部分是SpringBoot引入Swagger的两种方式,第二部分是详细介绍在Web接口上应用Swagger的注解。

本篇文章使用SpringBoot 2.1.10.RELEASE和springfox-swagger 2.9.2

一、SpringBoot引入Swagger的两种方式

目前SpringBoot有两种使用Swagger的方式:

引入swagger原生依赖springfox-swagger2和springfox-swagger2-ui

引入国内Spring4All社区开发的依赖swagger-spring-boot-starter

Spring4All出品的依赖采取配置文件的方式进行配置,而原生依赖是通过java config类来设置的。

1.1 原生配置Swagger

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>

swagger配置类:

/**
 * swagger2配置类
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {
 @Bean
 public Docket createRestApi() {
  return new Docket(DocumentationType.SWAGGER_2)
    .apiInfo(apiInfo())
    .select()
    .apis(RequestHandlerSelectors.basePackage("com.example"))
    .paths(PathSelectors.any())
    .build();
 }

 private ApiInfo apiInfo() {
  return new ApiInfoBuilder()
    .title("基于Swagger构建的Rest API文档")
    .description("更多请咨询服务开发者eknown")
    .contact(new Contact("空夜", "http://www.eknown.cn", "eknown@163.com"))
    .termsOfServiceUrl("http://www.eknown.com")
    .version("1.0")
    .build();
 }
}

从这里可以看出Swagger的一个缺点:无法通过SpringBoot的配置文件进行配置,所以配置并不能灵活转变。

spring4all社区出品的swagger-spring-boot-starter可以解决这个问题。

1.2 基于spring4all配置swagger

Spring4All社区的博主程序猿DD和小火两个人开发了Spring Boot Starter Swagger,目前已经在maven官方仓库上线了。

选择第一个,引入该依赖:

<dependency>
 <groupId>com.spring4all</groupId>
 <artifactId>swagger-spring-boot-starter</artifactId>
 <version>1.9.0.RELEASE</version>
</dependency>

这种方式的Swagger配置是通过application配置文件进行的。下面给出一个示例:

server:
 port: 8106
swagger:
 base-path: /**
 base-package: 'com.example'
 title: 'spring-boot-swagger-demo'
 description: '基于Swagger构建的SpringBoot RESTApi 文档'
 version: '1.0'
 contact:
 name: '空夜'
 url: 'http://www.eknown.cn'
 email: 'eknown@163.com'

二、应用Swagger构建接口可视化

2.1 Controller类添加Swagger注解

下面给一个简单的示例:

@Api(tags = "用户管理")
@RestController
@RequestMapping(value = "user")
public class UserController {

 // 模拟数据库存储的用户
 private static Map<Integer, User> userMap;

 static {
  userMap = new ConcurrentHashMap<>();
  User user = new User(0, "admin", true, new Date());
  userMap.put(user.getId(), user);
 }

 @ApiOperation("列表查询")
 @GetMapping(value = "")
 public List<User> list() {
  return new ArrayList<>(userMap.values());
 }

 @ApiOperation(value = "获取用户详细信息", notes = "路径参数ID")
 @GetMapping(value = "{id}")
 public User detail(@PathVariable Integer id) {
  return userMap.get(id);
 }

 @ApiOperation(value = "新增或更新用户信息", notes = "insert和update共用"
   , response = User.class)
 @PostMapping(value = "")
 public User add(@RequestBody User user) {
  if (user == null || user.getId() == null || !StringUtils.isEmpty(user.getName())
    || userMap.containsKey(user.getId())) {
   return null;
  }

  user.setUpdateTime(new Date());
  userMap.put(user.getId(), user);
  return user;
 }

 @ApiOperation(value = "删除用户")
 @DeleteMapping(value = "{id}")
 public Boolean delete(@ApiParam(name = "用户ID", required = true, example = "100") @PathVariable Integer id) {
  if (userMap.containsKey(id)) {
   userMap.remove(id);
   return true;
  }

  return false;
 }

}

2.2 参数实体类添加Swagger注解

实体类也需要添加一些注解,以便前端开发人员确定参数的意义、类型、示例等。

@ApiModel(description = "用户类")
public class User {

 @ApiModelProperty(value = "ID", example = "100")
 private Integer id;

 @ApiModelProperty(value = "姓名", example = "laolunsi")
 private String name;

 @ApiModelProperty(value = "是否启用", example = "1")
 private Boolean enable;

 @ApiModelProperty("更新时间")
 private Date updateTime;

 public User(Integer id, String name, Boolean enable, Date updateTime) {
  this.id = id;
  this.name = name;
  this.enable = enable;
  this.updateTime = updateTime;
 }

 // ... ignore getter and setter methods
}

2.3 测试

启动项目,访问http://localhost:port/swagger-ui.html

如果存在server.servlet.context-path配置,那么访问地址是http://localhost:port/context-path/swagger-ui.html

这样,接口就一目了然了,swagger还支持在线测试接口,与postman的作用类似。

好,到目前为止,我们已经成功在SpringBoot项目中整合了Swagger,这样前后端开发对接就有了标准!

以上就是Spring Boot 使用 Swagger 构建 RestAPI 接口文档的详细内容,更多关于Spring Boot 整合 Swagger的资料请关注我们其它相关文章!

(0)

相关推荐

  • Spring Boot引入swagger-ui 后swagger-ui.html无法访问404的问题

    最近给graphserver增加swagger,记录下过程与问题解决. Swagger 是一个规范和完整的框架,用于生成.描述.调用和可视化 RESTful 风格的 Web 服务,后端集成下Swagger,然后就可以提供一个在线文档地址给前端同学. 引入 Swagger pom中加入相关配置: <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</art

  • Springboot引入拦截器并放行swagger代码实例

    这篇文章主要介绍了Springboot引入拦截器并放行swagger代码实例,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友可以参考下 Springboot引入拦截器 自定义的拦截器类 Interceptor package cn.zytao.taosir.auth.config; import javax.annotation.Resource; import javax.servlet.http.HttpServletRequest; import j

  • SpringBoot整合Swagger3生成接口文档过程解析

    前后端分离的项目,接口文档的存在十分重要.与手动编写接口文档不同,swagger是一个自动生成接口文档的工具,在需求不断变更的环境下,手动编写文档的效率实在太低.与新版的swagger3相比swagger2配置更少,使用更加方便. 一.pom文件中引入Swagger3依赖 <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId

  • SpringBoot集成SwaggerUi以及启动时遇到的错误

    SwaggerUi是一个自动生成接口文档,并且还可以去测试这些接口的东西. SpringBoot集成SwaggerUi 引入依赖 <properties> <swagger.version>2.6.1</swagger.version> </properties> <dependencies> <dependency> <groupId>org.springframework.boot</groupId> &l

  • spring boot-2.1.16整合swagger-2.9.2 含yml配置文件的代码详解

    java代码 package com.oauth.util; import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import springfox.documentat

  • SpringBoot2.0集成Swagger2访问404的解决操作

    最近使用最新的SpringBoot2.0集成Swagger2的时候遇到一个问题,集成之后打开Swagger页面的时候出现404,后台提示找不到swagger-ui的页面. 于是我看了下项目依赖swagger的结构: 可以看到 swagger-ui.html 在META-INF/resources目录下,所以我们需要手动的将静态资源路径指向这里,在java中配置为: import org.springframework.context.annotation.Bean; import org.spr

  • SpringBoot如何优雅地使用Swagger2

    前言 Spring Boot 框架是目前非常流行的微服务框架,我们很多情况下使用它来提供 Rest API.而对于 Rest API 来说很重要的一部分内容就是文档,Swagger 为我们提供了一套通过代码和注解自动生成文档的方法,这一点对于保证 API 文档的及时性将有很大的帮助.本文将使用 Swagger 2 规范的 Springfox 实现来了解如何在 Spring Boot 项目中使用 Swagger,主要包含了如何使用 Swagger 自动生成文档.使用 Swagger 文档以及 Sw

  • Spring Boot 使用 Swagger 构建 RestAPI 接口文档

    源码地址:https://github.com/laolunsi/spring-boot-examples 目前SpringBoot常被用于开发Java Web应用,特别是前后端分离项目.为方便前后端开发人员进行沟通,我们在SpringBoot引入了Swagger. Swagger作用于接口,让接口数据可视化,尤其适用于Restful APi 本节分两部分介绍,第一部分是SpringBoot引入Swagger的两种方式,第二部分是详细介绍在Web接口上应用Swagger的注解. 本篇文章使用Sp

  • spring boot集成smart-doc自动生成接口文档详解

    目录 前言 功能特性 1 项目中创建 /src/main/resources/smart-doc.json配置文件 2 配置内容如下(指定文档的输出路径) 3 pom.xml下添加配置 4 运行插件 5 找到存放路径浏览器打开 6 测试结果 前言 smart-doc 是一款同时支持 java restful api 和 Apache Dubbo rpc 接口文档生成的工具,smart-doc 颠覆了传统类似 swagger 这种大量采用注解侵入来生成文档的实现方法. smart-doc 完全基于

  • Spring Cloud Gateway 整合 knife4j 聚合接口文档功能

    当系统中微服务数量越来越多时,如果任由这些服务散落在各处,那么最终管理每个项目的接口文档将是一件十分麻烦的事情,单是记住所有微服务的接口文档访问地址就是一件苦差事了.当如果能够将所有微服务项目的接口文档都统一汇总在同一个可视化页面,那么将大大减少我们的接口文档管理维护工作,为此,我们可以基于 Spring Cloud Gateway 网关 + nacos + knife4j 对所有微服务项目的接口文档进行聚合,从而实现我们想要的文档管理功能 注:本案例需要 springboot 提前整合 nac

  • SpringBoot使用swagger生成api接口文档的方法详解

    目录 前言 具体例子 maven配置 项目application.yml配置 springApplication添加swagger注解 在控制层添加swagger注解 前言 在之前的文章中,使用mybatis-plus生成了对应的包,在此基础上,我们针对项目的api接口,添加swagger配置和注解,生成swagger接口文档 具体可以查看本站spring boot系列文章: spring boot项目使用mybatis-plus代码生成实例 具体例子 maven配置 在使用之前,我们需要添加s

  • 教你利用springboot集成swagger并生成接口文档

    效果图 实现步骤 1.maven中引入jar包,不同版本的swagger可能页面效果不一样. <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.1</version> </dependency> <dependency> <groupId&g

  • .NET Core利用swagger进行API接口文档管理的方法详解

    一.问题背景 随着技术的发展,现在的开发模式已经更多的转向了前后端分离的模式,在前后端开发的过程中,联系的方式也变成了API接口,但是目前项目中对于API的管理很多时候还是通过手工编写文档,每次的需求变更只要涉及到接口的变更,文档都需要进行额外的维护,如果有哪个小伙伴忘记维护,很多时候就会造成一连续的问题,那如何可以更方便的解决API的沟通问题?Swagger给我们提供了一个方式,由于目前主要我是投入在.NET Core项目的开发中,所以以.NET Core作为示例 二.什么是Swagger S

  • Spring Boot 集成 Swagger2构建 API文档

    目录 一.Swagger是什么 1.SwaggerEditor 2.SwaggerUI 3.SwaggerCodegen 4.SwaggerUI 二.SpringBoot集成Swagger 1.创建SpringBoot项目 2.引入依赖 3.构建Swagger配置类 4.编写接口 5.查看并测试接口 前言: 不管你是从事前端还是后端开发,相信都难免被接口文档折磨过.如果你是一个前端开发者,可能你会经常发现后端给的接口文档跟实际代码有所出入.而假设你是一个后端开发者,你可能又会觉得自己开发后端接口

  • Spring boot集成swagger2生成接口文档的全过程

    一.Swagger介绍 Swagger是一个规范和完整的框架,用于生成.描述.调用和可视化RESTful风格的web服务.目标是使客户端和文件系统作为服务器以同样的速度来更新文件的方法,参数和模型紧密集成到服务器.这个解释简单点来讲就是说,swagger是一款可以根据restful风格生成的接口开发文档,并且支持做测试的一款中间软件. 二.使用swagger优势 1.对于后端开发人员来说 不用再手写Wiki接口拼大量参数,避免手写错误 对代码侵入性低,采用全注解的方式,开发简单 方法参数名修改.

  • Spring Boot项目集成Knife4j接口文档的实例代码

    目录 1.在pom.xml引入依赖包 2.创建Knife4j配置文件 3.使用Knife4j注解 4.全局参数 Knife4j就相当于是swagger的升级版,对于我来说,它比swagger要好用得多 1.在pom.xml引入依赖包 <!-- Swagger配置依赖knife4j --> <dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>knife4j-spring-b

  • 使用Spring Boot 2.x构建Web服务的详细代码

    目录 架构: 库: 运行应用的步骤 关于项目配置 Web服务声明 示例 通用错误处理 示例 Spring Data(JPA)配置 Entity类 Repository接口 在application.properties中的JPA数据库配置 数据库配置 application.properties application-dev.properties application-pro.properties 数据库密码加密 SampleWebservice.java JWT身份验证配置 创建令牌的过程

随机推荐