后端开发中经常需要对移动客户端提供RESTful API接口,在后期版本快速迭代的过程中,修改接口实现的时候都必须同步修改接口文档,而文档与代码又处于两个不同的媒介,除非有严格的管理机制,不然很容易导致写出的代码与接口文档不一致现象。

  Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。

  

1.在pom.xml中加入swagger2依赖

<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.2.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.2.2</version>
</dependency>

2.创建swagger2配置类

@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.offcn.controller"))
.paths(PathSelectors.any())
.build();
} private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Spring Boot中使用Swagger2构建RESTful APIs")
.description("描述描述")
.termsOfServiceUrl("http://www.baidu.com/")
.contact("Sunny")
.version("1.0")
.build();
}
}

3.Controller增加文档注释

通过@ApiImplicitParams@ApiImplicitParam注解来给参数增加说明

 @RestController
@EnableConfigurationProperties({User.class})
@RequestMapping("/user")
public class UserController { @Autowired
User user; private List<User> listUser= Collections.synchronizedList(new ArrayList<User>()); //查询所有
@GetMapping("/")
@ApiOperation(value="查询All用户信息", notes="All用户信息")
public List<User> getAllUser(){
return listUser;
}
//获取指定id的user
@GetMapping("/{id}")
@ApiOperation(value="查询指定id用户信息", notes="根据id查用户信息")
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long")
public User getUser(@PathVariable("id") Long id){
for(User u:listUser){
if(u.getId()==id){
return user;
}
}
return null;
}
//插入
@PostMapping("/")
@ApiOperation(value="插入用户", notes="插入用户信息")
@ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
public String insert(User user){
listUser.add(user);
return "success";
}
//根据id修改
@PutMapping("/{id}")
@ApiOperation(value="更新指定id用户信息", notes="根据id更新用户信息")
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long"),
@ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
})
public String update(@PathVariable("id") Long id,User user){
for (User user2 : listUser) {
if(user2.getId()==id) {
user2.setName(user.getName());
user2.setAge(user.getAge());
}
}
return "success";
}
//根据id删除
@DeleteMapping("/{id}")
@ApiOperation(value="删除指定id用户信息", notes="根据id删除用户信息")
@ApiImplicitParam(name = "id", value = "用户id", required = true, dataType = "Long")
public String delete(@PathVariable("id") Long id){
listUser.remove(getUser(id));
return "success";
} }

4.启动tomcat:

访问地址:http://localhost:8080/swagger-ui.html

即可看到上面的API

SpringBoot使用Swagger2构建API文档的更多相关文章

  1. Spring Boot中使用Swagger2构建API文档

    程序员都很希望别人能写技术文档,自己却很不愿意写文档.因为接口数量繁多,并且充满业务细节,写文档需要花大量的时间去处理格式排版,代码修改后还需要同步修改文档,经常因为项目时间紧等原因导致文档滞后于代码 ...

  2. springboot利用swagger构建api文档

    前言 Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件.本文简单介绍了在项目中集成swagger的方法和一些常见问题.如果想深入分析项目源码,了解更多内容,见参考资料. S ...

  3. Spring Boot 整合Swagger2构建API文档

    1.pom.xml中引入依赖 <dependency> <groupId>io.springfox</groupId> <artifactId>spri ...

  4. springboot+mybatis-puls利用swagger构建api文档

    项目开发常采用前后端分离的方式.前后端通过API进行交互,在Swagger UI中,前后端人员能够直观预览并且测试API,方便前后端人员同步开发. 在SpringBoot中集成swagger,步骤如下 ...

  5. SpringBoot+rest接口+swagger2生成API文档+validator+mybatis+aop+国际化

    代码地址:JillWen_SpringBootDemo mybatis 1. 添加依赖: <dependency> <groupId>org.mybatis.spring.bo ...

  6. springboot学习-jdbc操作数据库--yml注意事项--controller接受参数以及参数校验--异常统一管理以及aop的使用---整合mybatis---swagger2构建api文档---jpa访问数据库及page进行分页---整合redis---定时任务

    springboot学习-jdbc操作数据库--yml注意事项--controller接受参数以及参数校验-- 异常统一管理以及aop的使用---整合mybatis---swagger2构建api文档 ...

  7. 白话SpringCloud | 第十一章:路由网关(Zuul):利用swagger2聚合API文档

    前言 通过之前的两篇文章,可以简单的搭建一个路由网关了.而我们知道,现在都奉行前后端分离开发,前后端开发的沟通成本就增加了,所以一般上我们都是通过swagger进行api文档生成的.现在由于使用了统一 ...

  8. 使用springfox+swagger2书写API文档(十八)

    使用springfox+swagger2书写API文档 springfox是通过注解的形式自动生成API文档,利用它,可以很方便的书写restful API,swagger主要用于展示springfo ...

  9. Spring Boot中使用Swagger2自动构建API文档

    由于Spring Boot能够快速开发.便捷部署等特性,相信有很大一部分Spring Boot的用户会用来构建RESTful API.而我们构建RESTful API的目的通常都是由于多终端的原因,这 ...

随机推荐

  1. Linux 查看 添加 修改路由

    最近搭建vpn, 使用 ssh 隧道一直在涉及路由相关问题,今天简单整理一下,方便下次使用: 查看路由: [jsi@localhost Desktop]$ route Kernel IP routin ...

  2. mysql里面alter的用法

    1:删除列 ALTER TABLE [表名字] DROP [列名称] 2:增加列 ALTER TABLE [表名字] ADD [列名称] INT NOT NULL  COMMENT '注释说明' 3: ...

  3. 九、Swift对象存储服务(双节点搭建)

    九.Swift对象存储服务(双节点搭建) 要求:Controoler节点需要2块空盘 Compute节点需要再加2块空盘 本次搭建采用Controller 和 Compute双节点节点做swift组件 ...

  4. 字典与json转化

    json.dumps(字典)  #转成json格式 json.loads(json格式) #转成字典格式

  5. -shared -fPIC

    gcc -shared -fPIC -o 1.so 1.c   这里有一个-fPIC参数 PIC就是position independent code PIC使.so文件的代码段变为真正意义上的共享

  6. Pwnable-random

    ssh连接,输入密码查看目录下的文件 看看random.c的源码 #include <stdio.h> int main(){ unsigned int random; random = ...

  7. django DeleteView

    DeleteView from django.urls import reverse, reverse_lazy from django.contrib.auth.mixins import Logi ...

  8. CentOs篇

    Advanced-高级配置.Security-安全.Boot-启动引导: 1.Removable Devices-移动设备 2.Hard Drive-本地硬盘 3.CD-ROM- Drive-光盘 4 ...

  9. 实时获取input框内容

    源码: <%@ page language="java" contentType="text/html; charset=utf-8" pageEncod ...

  10. GitHub 注册失败的原因 以及解决 。

    1.注册的时候老是卡在第一步: 提交用户名和密码 还有邮箱的时候 提交成功后. 不跳出 第二步.若现在去登录账号和密码,不管输对的还是输错的都是显示错误的.2.查看GitHub官网帮助后,不难发现问题 ...