Springfox 解决在单一资源操作多个方法实现时生成 Swagger 文档的问题

在命名本文的标题都敲打了几分钟时间,问题很简单,然而用简短的一个标题完全描述出来却有点费事。在 Spring MVC 项目结合 Springfox 来生成 Swagger API 文档时,如果一个资源操作因为请求参数的不同而映射到多个 controller 方法,那么 Swagger 可能只能生成某一个 API 条目,其余都被忽略。至于为什么说是 "可能", 可能正好未遵循命名规范而躲过了这一劫。由此引出

我们的问题

我们这里用了资源操作一词,它包含了两部分信息: 资源与操作,比如 /users/{userId} 是资源,而发生在其上的 HTTP 各种方法,如 POST, GET, PUT, DELETE 等就是操作。而 Spring MVC 中允许我们针对不同的查询参数把相同的资源操作映射到不同的 controller 方法上,也是为了保持逻辑上更为清晰。

比如下面的例子路由配置的例子

GET /users/{userId}     UserController.getUserInfo                                    //默认
GET /users/{userId}     UserController.getUserInfo                                   //当有 ?source=file 时
GET /users/{userId}     CloudUserController.getUserInfoFromCloud       //当有 ?source=cloud 时

看到上面资源与操作完全相同,仅仅因为 source 查询参数的不同而映射到三个 controller 方法。用代码体现如下图 阅读全文 >>

类别: Spring. 标签: , , . 阅读(100). 评论(0) »

如果要给 RESTful 每种 HTTP Method 类型指示一种颜色

RESTful 时需要考虑每种 HTTP Method 操作的业务含义,再也不是 GET 使用 URL, POST 提交表单这样简单的区别。http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html 定义有 GET, POST, PUT, HEAD, DELETE, PATCH, OPTIONS, TRACE, CONNECT 九种类型的 HTTP Method。

关于它们可能针对的业务含义就不多说了,而是如果要对每一种操作方法赋予一个颜色应该怎么去对应呢,比如一般 GET 不会有边际效应的操作可以选择绿色,或者蓝色。幸好我也不用多想,这里参考了 Swagger 的颜色方案,它支持除 OPTIONS, TRACE 和 CONNECT 之外的颜色配置,其实我也没用过这两种方法。

从 Play2 Swagger 中截图如下: 阅读全文 >>

类别: Web/JS. 标签: , , . 阅读(187). 评论(0) »

RESTful, 说说 http 的 patch method

最早的时候,我们只需要 GET 和 POST 方法,POST 方法的引入也只是为了消除 URL 过长,参数隐藏,上传文件的问题,完全和语义无关。接触到 RESTful 之后,我们开始思考 GET 和 POST 的不同语义,并且十分必要的去发掘出所有的 HTTP method,HTTP/1.1 所实现的 method,见 RFC 2616, 有这些:

OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, CONNECT

规范是这么定义的,这还要看容器实现了多少,比如 Tomcat 7 中的 servlet api 实现了

doOptions, doGet, doHead, doPost, doPut, doDelete, doTrace 就差个 doConnect 了。

而我们这里要说的 PATCH method 是在 Servlet 3.0 和当前 Tomcat 7 中都提到的,也就是尚未实现它。

这也难怪,PATCH 在 2010 年三月份才成为正式的方法,见 RFC 5789。没有 PATCH 的时候我们进行更新的操作采用的是 PUT 方法。那么 PATCH 和 PUT 有什么区别呢?

同样可以从语义上去理解,有两方面的对比: 阅读全文 >>

类别: Java/JEE. 标签: , . 阅读(18,209). 评论(1) »