一、swagger2.0，resful，openApi3.0是什么？
就是URI包含动词：因为"资源"表示一种实体，所以应该是名词，
URI中加入版本号:因为不同的版本，可以理解成同一种资源的不同表现形式，所以应该采用同一个URI。版本号可以在HTTP请求头信息的Accept字段中进行区分
总结: 实际工作中restful跟swagger的意义和使用
前言
面对层出不穷的语言，java为何屹立多年不倒。论简单不如python，性能上不如go，为什么大规模开发依然首选java。作为一名架构师，我深刻感悟着java之美。java的美和优势在于规范，虽然python，go也都有面向对象的设计和支持，但是在实践中往往都是面向过程。虽然都有各种代码要求但是在实践中往往都是随心所欲。优秀的java的逻辑能够让所有java人读懂，但是go和python就算是资深人员想去读懂别人，也需要些时间。swagger是一种规范，一种基于resful的规范。而二者是描绘接口协议的，今天我们一起去研读一下。
一、swagger2.0，resful，openApi3.0是什么？
resful是一种http协议规范，规定了常见的增删改查在控制层的语义体现，比如查询用get。。。
也是面向资源编程的体现。swagger2.0在resful基础上，规定了更多的细节，比如返回结构应该是什么样的，版本应该叫做什么，放在哪里。openApi3.0是swagger2.0的升级，当时swagger是基于apache的一些规范指定的，后来被Apache组织吸纳为开源项目，就在swagger2.0基础上完善，变成了openApi3.0，二者是父子关系，所以不存在openApi2.0或者swagger3.0.
二、restful协议的内容
1.restful
resful的全称：Resources Representational State Transfer资源的表现成状态转化，所谓"资源"，就是网络上的一个实体，或者说是网络上的一个具体信息。它可以是一段文本、一张图片、一首歌曲、一种服务，总之就是一个具体的实在。GET用来获取资源，POST用来新建资源（也可以用于更新资源），PUT用来更新资源，DELETE用来删除资源。
2.reful协议的误区
-
就是URI包含动词：因为"资源"表示一种实体，所以应该是名词，
举例来说，某个URI是/posts/show/1，其中show是动词，这个URI就设计错了，正确的写法应该是/posts/1，然后用GET方法表示show。
如果某些动作是HTTP动词表示不了的，你就应该把动作做成一种资源。比如网上汇款，从账户1向账户2汇款500元，错误的URI是：
POST /accounts/1/transfer/500/to/2正确的写法是把动词transfer改成名词transaction，资源不能是动词，但是可以是一种服务：
/transaction?from=1&to=2&amount=500.00-
URI中加入版本号:因为不同的版本，可以理解成同一种资源的不同表现形式，所以应该采用同一个URI。版本号可以在HTTP请求头信息的Accept字段中进行区分
3.GET，DELETE，PUT和POST的典型用法:
GET
- 安全且幂等
- 获取表示
- 变更时获取表示（缓存）
- 200（OK） - 表示已在响应中发出
- 204（无内容） - 资源有空表示
- 301（Moved Permanently） - 资源的URI已被更新
- 303（See Other） - 其他（如，负载均衡）
- 304（not modified）- 资源未更改（缓存）
- 400 （bad request）- 指代坏请求（如，参数错误）
- 404 （not found）- 资源不存在
- 406 （not acceptable）- 服务端不支持所需表示
- 500 （internal server error）- 通用错误响应
- 503 （Service Unavailable）- 服务端当前无法处理请求
POST
- 不安全且不幂等
- 使用服务端管理的（自动产生）的实例号创建资源
- 创建子资源
- 部分更新资源
- 如果没有被修改，则不过更新资源（乐观锁）
- 200（OK）- 如果现有资源已被更改
- 201（created）- 如果新资源被创建
- 202（accepted）- 已接受处理请求但尚未完成（异步处理）
- 301（Moved Permanently）- 资源的URI被更新
- 303（See Other）- 其他（如，负载均衡）
- 400（bad request）- 指代坏请求
- 404 （not found）- 资源不存在
- 406 （not acceptable）- 服务端不支持所需表示
- 409 （conflict）- 通用冲突
- 412 （Precondition Failed）- 前置条件失败（如执行条件更新时的冲突）
- 415 （unsupported media type）- 接受到的表示不受支持
- 500 （internal server error）- 通用错误响应
- 503 （Service Unavailable）- 服务当前无法处理请求
PUT
- 不安全但幂等
- 用客户端管理的实例号创建一个资源
- 通过替换的方式更新资源
- 如果未被修改，则更新资源（乐观锁）
- 200 （OK）- 如果已存在资源被更改
- 201 （created）- 如果新资源被创建
- 301（Moved Permanently）- 资源的URI已更改
- 303 （See Other）- 其他（如，负载均衡）
- 400 （bad request）- 指代坏请求
- 404 （not found）- 资源不存在
- 406 （not acceptable）- 服务端不支持所需表示
- 409 （conflict）- 通用冲突
- 412 （Precondition Failed）- 前置条件失败（如执行条件更新时的冲突）
- 415 （unsupported media type）- 接受到的表示不受支持
- 500 （internal server error）- 通用错误响应
- 503 （Service Unavailable）- 服务当前无法处理请求
DELETE
- 不安全但幂等
- 删除资源
- 200 （OK）- 资源已被删除
- 301 （Moved Permanently）- 资源的URI已更改
- 303 （See Other）- 其他，如负载均衡
- 400 （bad request）- 指代坏请求
- 404 （not found）- 资源不存在
- 409 （conflict）- 通用冲突
- 500 （internal server error）- 通用错误响应
- 503 （Service Unavailable）- 服务端当前无法处理请求
综上：
查询：用Get http://资源url/{资源id}
新增和修改：用post和put，区别在于所创建的资源的名称(URI)是否由客户端决定。 更为通用的方式是post用于新增，put用于修改，
删除：delete
示例：一个user的管理
GET: http：//user?{userId}
POST: http://user body体:{user对象}
PUT: http：//user?{userId} body体:{user对象}
DELETE: http：//user?{userId}
分别具化为user的增删改查
三.swagger协议
1.swagger2.0
restful规定了接口http url规范和返回的httpcode规范，但是如何用标准的计算机语言描述一个接口，而不是通过自然语义。这就是swagger以openApi干的事情，通过标准化的json文档或者yaml文档来描述
2.swagger的内容
https://swagger.io/tools/open-source/
https://download.csdn.net/download/habazhu1110/346411173.swagger官方文档速读
Definitions定义
- 路径模板是指使用花括号 ({}) 将 URL 路径的一部分标记为可使用路径参数替换。
- 子类型
text/plain; charset=utf-8
application/json
application/vnd.github+json
application/vnd.github.v3+json
application/vnd.github.v3.raw+json
application/vnd.github.v3.text+json
application/vnd.github.v3.html+json
application/vnd.github.v3.full+json
application/vnd.github.v3.diff
application/vnd.github.v3.patch- HTTP Status Codes
Hypertext Transfer Protocol (HTTP) Status Code Registry 遵循标准规范
4.Specification 规格
-
Format格式
使用json或者是yaml的方式来描述
5.File Structure 文件结构
可以使用自定义部分，然后用$ref的方式来引用，规范的文件名应该叫做swagger.json
6.Data Types数据类型
包括了Integer。。。。。
7.Schema架构
这里特别说几个点
definitions ： 自定义的结构， 然后可以用$ref来引用
允许扩展 Swagger 架构。 字段名称必须以 x- 开头，例如 x-internal-id。 该值可以是 null、原始值、数组或对象。 有关更多详细信息，请参阅供应商扩展。
8.Info Object元数据
该对象提供有关 API 的元数据。 如果需要，客户端可以使用元数据，并且可以在 Swagger-UI 中呈现以方便使用。
9. Contact Object联系对象
10. License Object许可对象
11.Paths Object
get:
description: Returns pets based on ID
summary: Find pets by ID
operationId: getPetsById
produces:
- application/json
- text/html
responses:
'200':
description: pet response
schema:
type: array
items:
$ref: '#/definitions/Pet'
default:
description: error payload
schema:
$ref: '#/definitions/ErrorModel'
parameters:
- name: id
in: path
description: ID of pet to use
required: true
type: array
items:
type: string
collectionFormat: csv12.Operation Object 操作对象
......
里面层层迭代展开每一个jsonkey的含义.
总结: 实际工作中restful跟swagger的意义和使用
restful的意义在于能够面向资源展示语义, swagger的意义在于可以输出标准化的接口描述文档,然后与其他的平台和工具对接,比如swagger自带的工具.
实际工作中swagger文档的生成用的是工具生成, 解析上也有很多自动化工具可以把文档解析成bean, 甚至是根据文档可以生成自动化测试用例以及可视化页面.
2798
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
