时间:2021-05-20
源码地址: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@EnableSwagger2public 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://'二、应用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的资料请关注其它相关文章!
声明:本页内容来源网络,仅供用户参考;我单位不保证亦不表示资料全面及准确无误,也不保证亦不表示这些资料为最新信息,如因任何原因,本网内容或者用户因倚赖本网内容造成任何损失或损害,我单位将不会负任何法律责任。如涉及版权问题,请提交至online#300.cn邮箱联系删除。
网上有很多《使用swagger2构建API文档》的文章,该文档是一个在线文档,需要使用HTTP访问。但是在我们日常使用swagger接口文档的时候,有的时候需要
在使用spring-boot开发的时候,我们很多时候会使用swagger作为api文档输出。可以在UI界面上看到api的路径,参数等等。当然,作为开发环境是很方
上篇使用docker构建spring-boot应用,是把编译好的jar包构建到镜像中。这篇是把spring-boot连同数据库,做为一组docker服务运行起来
swagger介绍Swagger本质上是一种用于描述使用JSON表示的RESTfulAPI的接口描述语言。Swagger与一组开源软件工具一起使用,以设计、构建
一、简介Swagger的目标是为RESTAPI定义一个与语言无关的标准接口,允许用户发现和理解计算机服务的功能,而无需访问源代码。当通过Swagger正确定义时