Spring Cloud Spring Boot mybatis分布式微服务云架构(十)使用Swagger2构建强大的RESTful API文档(2)

原创 2018年03月09日 10:15:36

添加文档内容

在完成了上述配置后,其实已经可以生产文档内容,但是这样的文档主要针对请求本身,而描述主要来源于函数等命名产生,对用户并不友好,我们通常需要自己增加一些说明来丰富文档内容。如下所示,我们通过@ApiOperation注解来给API增加说明、通过@ApiImplicitParams@ApiImplicitParam注解来给参数增加说明。

@RestController
@RequestMapping(value="/users")     // 通过这里配置使下面的映射都在/users下,可去除
public class UserController {

    static Map<Long, User> users = Collections.synchronizedMap(new HashMap<Long, User>());

    @ApiOperation(value="获取用户列表", notes="")
    @RequestMapping(value={""}, method=RequestMethod.GET)
    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";
    }

}

完成上述代码添加上,启动Spring Boot程序,访问:http://localhost:8080/swagger-ui.html
。就能看到前文所展示的RESTful API的页面。我们可以再点开具体的API请求,以POST类型的/users请求为例,可找到上述代码中我们配置的Notes信息以及参数user的描述信息,如下图所示。

altalt

API文档访问与调试

在上图请求的页面中,我们看到user的Value是个输入框?是的,Swagger除了查看接口功能外,还提供了调试测试功能,我们可以点击上图中右侧的Model Schema(黄色区域:它指明了User的数据结构),此时Value中就有了user对象的模板,我们只需要稍适修改,点击下方“Try it out!”按钮,即可完成了一次请求调用!

此时,你也可以通过几个GET请求来验证之前的POST请求是否正确。

相比为这些接口编写文档的工作,我们增加的配置内容是非常少而且精简的,对于原有代码的侵入也在忍受范围之内。因此,在构建RESTful API的同时,加入swagger来对API文档进行管理,是个不错的选择。

源码来源

在VC中实现程序在启动时隐藏

    最近经常见论坛上有人问,程序在启动时如何隐藏。以下是我总结的一些方法,欢迎大家讨论,找出更好的方法。    对于这类问题,大家最容易想到的可能就是在PreCreateWindow中添加cs.s...
  • AttaBoy
  • AttaBoy
  • 2002-03-03 09:18:00
  • 1228

Spring Boot学习(五)之使用Swagger2构建强大的RESTful API文档

随着前后端的分离,接口文档变的尤其重要,今天我们来说一说用SWAGGER2,来风骚的生成api文档。配置很简单,废话少说,直接上代码: pom.xml文件 01 parent> ...
  • zhaokejin521
  • zhaokejin521
  • 2017-11-10 10:08:56
  • 156

Spring Boot Swagger2 构建RESTful API

  • 2016年12月30日 15:31
  • 41KB
  • 下载

Spring Boot中使用Swagger2构建RESTful API文档

转载声明:商业转载请联系作者获得授权,非商业转载请注明出处 © wekri 随着时间推移,不断修改接口实现的时候都必须同步修改接口文档,而文档与代码又处于两个不同的媒介,除非有严格的管理机制...
  • Eacter
  • Eacter
  • 2017-02-23 15:01:25
  • 4016

微服务架构 - Spring Boot中使用Swagger2构建强大的RESTful API文档

由于Spring Boot能够快速开发、便捷部署等特性,相信有很大一部分Spring Boot的用户会用来构建RESTful API。而我们构建RESTful API的目的通常都是由于多终端的原因,这...
  • u011537073
  • u011537073
  • 2017-05-24 10:08:19
  • 820

Spring Cloud微服务分布式云架构 - spring cloud集成项目

Spring Cloud集成项目有很多,下面我们列举一下和Spring Cloud相关的优秀项目...
  • qq_40354025
  • qq_40354025
  • 2017-11-02 08:55:18
  • 296

Spring Cloud分布式微服务云架构源码分析 — Eureka

在看具体源码前,我们先回顾一下之前我们所实现的内容,从而找一个合适的切入口去分析。首先,服务注册中心、服务提供者、服务消费者这三个主要元素来说,后两者(也就是Eureka客户端)在整个运行机制中是大部...
  • qq_40354025
  • qq_40354025
  • 2017-12-05 09:06:25
  • 393

《Spring Cloud构建微服务架构》系列博

http://blog.didispace.com/categories/Spring-Cloud/ 《Spring Cloud构建微服务架构》系列博文示例 chapter1-1-1:Sprin...
  • u013322876
  • u013322876
  • 2017-03-11 13:58:14
  • 3258

Spring Cloud Spring Boot mybatis分布式微服务云架构(一)快速入门

快速入门本章主要目标完成Spring Boot基础项目的构建,并且实现一个简单的Http请求处理,通过这个例子对Spring Boot有一个初步的了解,并体验其结构简单、开发快速的特性。系统要求:Ja...
  • qq_40354025
  • qq_40354025
  • 2018-02-28 09:28:36
  • 199

使用spring cloud代建完整的分布式微服务架构

  • 2017年04月14日 11:19
  • 355KB
  • 下载
收藏助手
不良信息举报
您举报文章:Spring Cloud Spring Boot mybatis分布式微服务云架构(十)使用Swagger2构建强大的RESTful API文档(2)
举报原因:
原因补充:

(最多只允许输入30个字)