关键词:
SpringBoot2.3.0集成Swagger2
背景:最近在工作中发现,已经多次发现后台开发人员提供的接口协议和实际的业务代码不统一。这些现象往往都是因为开发人员在对接口协议调整后没有及时进行协议文档的更新造成的。
引入Swagger2相应的依赖
在SprintBoot中引入Swagger2依赖包很简单,在pom.xml文件中引入相应的依赖即可。
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.8.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.8.0</version>
</dependency>
入门示例
我们创建一个入门的Springboot项目。项目整体目录结构如下:
然后编写一个DemoController类,在类中添加几个方法,具体如下:
package com.majing.learning.springboot.swagger2.controller;
import com.majing.learning.springboot.swagger2.entity.User;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.*;
import java.util.*;
@RestController
@Api(tags = "用户管理相关接口")
@RequestMapping(value="/users")
public class DemoController
static Map<Long, User> users = Collections.synchronizedMap(new HashMap<>());
static
users.put(1L, new User(1L,"majing1", "31"));
users.put(2L, new User(2L,"majing2", "32"));
users.put(3L, new User(3L,"majing3", "33"));
users.put(4L, new User(4L,"majing4", "34"));
@ApiOperation(value="获取用户列表", notes="")
@RequestMapping(value="", method= RequestMethod.GET)
@ApiResponses(value=@ApiResponse(code=9001, message="OK"),@ApiResponse(code=9002, message="ERROR"))
public List<User> getUserList()
List<User> r = new ArrayList<User>(users.values());
return r;
@ApiOperation(value="创建用户", notes="根据User对象创建用户")
@ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
@RequestMapping(value="/", method=RequestMethod.POST)
public String postUser(@RequestBody User user)
users.put(user.getId(), user);
return "success";
@ApiOperation(value="获取用户详细信息", notes="根据url的id来获取用户详细信息")
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long")
@RequestMapping(value="/id", method=RequestMethod.GET)
public User getUser(@PathVariable Long id)
return users.get(id);
@ApiOperation(value="更新用户详细信息", notes="根据url的id来指定更新对象,并根据传过来的user信息来更新用户详细信息")
@ApiImplicitParams(
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long"),
@ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
)
@RequestMapping(value="/id", method=RequestMethod.PUT)
public String putUser(@PathVariable Long id, @RequestBody User user)
User u = users.get(id);
u.setName(user.getName());
u.setAge(user.getAge());
users.put(id, u);
return "success";
@ApiOperation(value="删除用户", notes="根据url的id来指定删除对象")
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long")
@RequestMapping(value="/id", method=RequestMethod.DELETE)
public String deleteUser(@PathVariable Long id)
users.remove(id);
return "success";
对于上面的实体类User定义如下:
package com.majing.learning.springboot.swagger2.entity;
import io.swagger.annotations.ApiModel;
@ApiModel
public class User
private Long id;
private String name;
private String age;
public User(long id, String name, String age)
this.id = id;
this.name = name;
this.age = age;
public Long getId()
return id;
public void setId(Long id)
this.id = id;
public String getName()
return name;
public void setName(String name)
this.name = name;
public String getAge()
return age;
public void setAge(String age)
this.age = age;
为了使用Swagger2,需要在应用启动类同级目录加上Swagger2的配置及注解,具体如下:
package com.majing.learning.springboot.swagger2;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class Swagger2Config
@Bean
public Docket createRestApi()
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.majing.learning.springboot.swagger2.controller"))
.paths(PathSelectors.any())
.build();
private ApiInfo apiInfo()
return new ApiInfoBuilder()
.title("Spring Boot中使用Swagger2构建RESTful APIs")
.description("测试使用Swagger2生成API文档")
.termsOfServiceUrl("https://***.com/")
.contact("马靖")
.version("1.0")
.build();
接下来我们启动应用程序,然后访问http://localhost:5002/swagger-ui.html,即可看到自动生成的API文档。这里的端口根据需要在application.properties文件自行调整。
至此,在SpringBoot2中集成Swagger2便完成了,看了下生成的API文档,感觉还是不错的。
SpringBoot2集成Swagger2后启动报错
上面的示例是没问题的,但是最开始尝试集成Swagger2时遇到个启动报错,其中有一段错误信息如下:
AnnotationConfigServletWebServerApplicationContext: Exception encountered during context initialization - cancelling refresh attempt: org.springframework.beans.factory.UnsatisfiedDependencyException: Error creating bean with name 'linkDiscoverers' defined in class path resource [org/springframework/hateoas/config/HateoasConfiguration.class]: Unsatisfied dependency expressed through method 'linkDiscoverers' parameter 0; nested exception is org.springframework.beans.factory.NoUniqueBeanDefinitionException: No qualifying bean of type 'org.springframework.plugin.core.PluginRegistry<org.springframework.hateoas.client.LinkDiscoverer, org.springframework.http.MediaType>' available: expected single matching bean but found 15: modelBuilderPluginRegistry,modelPropertyBuilderPluginRegistry,typeNameProviderPluginRegistry,documentationPluginRegistry,apiListingBuilderPluginRegistry,operationBuilderPluginRegistry,parameterBuilderPluginRegistry,expandedParameterBuilderPluginRegistry,resourceGroupingStrategyRegistry,operationModelsProviderPluginRegistry,defaultsProviderPluginRegistry,pathDecoratorRegistry,relProviderPluginRegistry,linkDiscovererRegistry,entityLinksPluginRegistry
刚开始看到这个错误有点懵逼,后来百度了下,说是Swagger2版本和Springboot版本不兼容导致,所以就修改了下Swagger2的版本,用了2.8.0,我自己的SpringBoot版本是2.3.0,重新启动了下,发现问题真的没有了。这里做个记录。
结语
上面我们通过Swagger2实现了后台代码动态生成和更新API文档,非常方便。但是有个缺点是没有访问权限的控制,数据Mock等功能。而且存在一定的代码侵入。后来针对国内外的API接口管理平台给调研了下,主要看了下ShowDoc、阿里云的RAP和CRAP-API,觉得都还挺好用的,有需要的可以自己研究下,这三个都是可以支持私有化部署的。
springboot项目集成swagger2
一、前言现如今,前后端分离已经逐渐成为互联网项目一种标准的开发方式,前端与后端交给不同的人员开发,但是项目开发中的沟通成本也随之升高,这部分沟通成本主要在于前端开发人员与后端开发人员对WebAPI接口的沟通,... 查看详情
springboot2系列教程|集成swagger2构建强大的restfulapi文档
...。反正我是挺闲的,所以有时间写blog。今天给你们带来SpringBoot集成Swagger2的教程。什么是Swagger2Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化RESTful风格的Web服务。为什么使用Swagger2?相信刚开始不熟悉web开发... 查看详情
springboot集成swagger2出现api重复问题(代码片段)
今天集成swagger2出现,大量api接口重复的问题,如下图所示:每个接口有7个方法,根据排查是由于api接口没有指定特定方法导致。解决方法为@RequestMapping修改为@DeleteMapping,具体如下://删除@Request... 查看详情
springboot集成swagger2
...c;尽早解决”,最终导致问题集中爆发。3 方法1.新建SpringBoot-web项目2.导入Swagger2依赖<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> &l 查看详情
springboot——springboot集成swagger生成api文档(代码片段)
文章目录:1.写在前面2.步骤详解2.1pom文件中添加Swagger依赖2.2在application.properties核心配置文件中配置Swagger2.3编写需要生成API文档的控制层代码2.4编写Swagger的配置类2.5访问测试1.写在前面说到Swagger(丝袜哥),首... 查看详情
springboot集成swagger2(代码片段)
1、swagger简介 Swagger是一款RESTful接口的文档在线自动生成、功能测试功能框架。一个规范和完整的框架,用于生成、描述、调用和可视化RESTful风格的Web服务,加上swagger-ui,可以有很好的呈现。 当我们在后台的接口修... 查看详情
springboot2.x版本配置swagger2
参考技术A为什么要引入Swagger?有过后台开发和前端联调的人都会被接口文档折磨,更新不及时,文档和代码不一致,无法调试,swagger就是为了解决这个问题。看下swagger官方介绍Swagger是一个规范和完整的框架,用于生成、描述、... 查看详情
企业级springboot教程springboot集成swagger2,构建优雅的restfulapi
swagger,中文“拽”的意思。它是一个功能强大的api框架,它的集成非常简单,不仅提供了在线文档的查阅,而且还提供了在线文档的测试。另外swagger很容易构建restful风格的api,简单优雅帅气,正如它的名字。一、引入依赖<depe... 查看详情
springboot2基于swagger2生成离线api文档
参考技术AGithub:https://github.com/ChaselX/springboot-swagger2-offline-api-docGitee:https://gitee.com/chasel96/springboot-swagger2-offline-api-doc个人觉得旧版的配置简单许多,新版的配置按照官方demo的配置来做还是复杂了很多配置到Springboot项目中以后,在... 查看详情
springboot集成swagger2在线文档
目录SpringBoot集成Swagger2在线文档前言集成SpringBoot登录接口文档示例代码效果注解说明总结SpringBoot集成Swagger2在线文档前言不得不说,前后端分离开发的工作方式给我们带来诸多好处,让前后端攻城狮们顺畅了不少后端给前端提... 查看详情
springboot整合swagger2
一关于SwaggerSwagger能成为最受欢迎的RESTAPIs文档生成工具之一,有以下几个原因:Swagger可以生成一个具有互动性的API控制台,开发者可以用来快速学习和尝试API。Swagger可以生成客户端SDK代码用于各种不同的平台上的实现。Swagger... 查看详情
springboot入门:集成swagger2
本片文章是基于前一篇写的,《SpringBoot入门(六):集成treetable和zTree实现树形图》,本篇主要介绍了springboot集成swagger2。关于swagger的介绍,自行谷歌。我这里有在网上购买的相关视频资料,有需要可以呼叫我。1.引入相关依赖... 查看详情
springboot之swagger2集成
一、Swagger2简单介绍 Swagger2,它可以轻松的整合到SpringBoot中,并与SpringMVC程序配合组织出强大RESTfulAPI文档。它既可以减少我们创建文档的工作量,同时说明内容又整合入实现代码中,让维护文档和修改代码整合为一体,可以... 查看详情
springboot1.5.4集成swagger2构建restfulapi(十八)
上一篇博客地址:springboot1.5.4整合rabbitMQ(十七)1 SpringBoot集成Swagger2构建RESTfulAPI文档1.1 Swagger2简介Swagger2官网:http://swagger.io/由于SpringBoot能够快速开发、便捷部署等特性,相信有很大一部分SpringBoo 查看详情
springboot+vue+mysql代码生成集成系统管理
集成系统管理,基于springboot+elementui生成springboot基于mybatisplus的单表curd、关联表curd、基于用户端的curd生成框架对应的权限数据库脚本生成对应管理的elementui页面集成swagger2和权限系统集成客户端和服务端数据校验码云: https... 查看详情
springboot中使用swagger2构建api文档
...动生成文档的插件.今天要介绍的就是Swagger.接下来我们在SpringBoot中使用Swagger2构建API文 查看详情
springboot之集成swagger2
maven配置<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.5.0</version></dependency><dependency>< 查看详情
springboot2,gradle集成swagger2
gradle文件增加//swaggerimplementation"io.springfox:springfox-swagger2:2.9.2"implementation"io.springfox:springfox-swagger-ui:2.9.2" 添加配置类SwaggerConfigpackagecom.zuo.model.config;importorg.springframework 查看详情