ServiceComb中的“卖身协议”
【摘要】 ServiceComb通过契约(Swagger)规范微服务开发，实现跨语言的通信、不同编程模型随意组合调用并只需提供一套handler处理链。虽然现在ServiceComb提供了自动生成契约(Swagger)的方式，但是在较早的版本中不支持自动生成或者因为项目的原因必须在服务端添加契约，手写契约又容易出现一些错误导致服务调用出错。
Swagger是什么：
Swagger是一个用于描述和记录RESTful APIs的项目(参考文档：https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md)。
Swagger的表现形式
根据Swagger规范描述的RESTful API的文件被表示为JSON对象并符合JSON标准。 作为JSON超集的YAML也可以用来表示Swagger规范文件，如：
字段名称简介
| Field Name | Type | Description |
|---|---|---|
| swagger | string | 指定使用的Swagger规格版本。 它可以被Swagger UI和其他客户端用来解释API列表。 该值必须是“2.0” |
| info | Info Object | 提供关于API的元数据。 如果需要，客户端可以使用元数据。 |
| host | string | 主机名或者IP |
| basePath | string | API的基本路径 |
| schemes | [string] | API的传输协议 |
| consumes | [string] | 可以使用的MIME类型列表。 这对所有的API都是全局的，但可以在特定的API调用上被覆盖。 值必须如MIME类型下所述 |
| produces | [string] | 与consumer类似 |
| paths | Paths Object | API的可用路径和方法 |
| definitions | Definitions Object | 一个对象，用于保存方法生成和使用的数据类型。 |
| parameters | Parameters Definitions Object | 方法的参数 |
| responses | Responses Definitions Object | 方法的返回类型 |
| securityDefinitions | Security Definitions Object | 安全方案定义 |
| security | [Security Requirement Object] | 宣布哪些安全计划适用于整个API。 值列表描述了可以使用的替代安全方案（即安全要求之间存在逻辑或）。 单独的操作可以覆盖此定义。 |
| tags | [Tag Object] | 规范使用附加元数据的标签列表。 |
| externalDocs | External Documentation Object | 额外的 外部文件 |
注：标红字段必须填写
一些MIME类型的定义：
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
Swagger中定义的参数类型
1.Path
2.Query
3.Header
4.Body
5.Form
If in is "body":
| Field Name | Type | Description |
|---|---|---|
| schema | Schema Object | Required. The schema defining the type used for the body parameter. |
这里要注意，如果参数类型为"body",则不能按下图所示书写
正确的写法是将类型写在Schema Object下，如：
在实际开发中很容易出现此错误
Swagger提供的一些注解
swagger-core提供了一系列的注解来达到生成生成契约文档(Swagger documentation)的目的，这些注解分为三大类：
声明资源
声明一个方法
声明API模型。
下面列举了一些swagger-core提供的注解及其作用
| @Api | Marks a class as a Swagger resource. |
| @ApiImplicitParam | Represents a single parameter in an API Operation. |
| @ApiImplicitParams | A wrapper to allow a list of multiple ApiImplicitParam objects. |
| @ApiModel | Provides additional information about Swagger models. |
| @ApiModelProperty | Adds and manipulates data of a model property. |
| @ApiOperation | Describes an operation or typically a HTTP method against a specific path. |
| @ApiParam | Adds additional meta-data for operation parameters. |
| @ApiResponse | Describes a possible response of an operation. |
| @ApiResponses | A wrapper to allow a list of multiple ApiResponse objects. |
| @Authorization | Declares an authorization scheme to be used on a resource or an operation. |
| @AuthorizationScope | Describes an OAuth2 authorization scope. |
| @ResponseHeader | Represents a header that can be provided as part of the response. |
在Swagger 2.0，class不再是一个resource，而是一个tag。@Api也被用来定义class中的所有方法，不再是用来声明resource。
【版权声明】本文为华为云社区用户翻译文章，如果您发现本社区中有涉嫌抄袭的内容，欢迎发送邮件进行举报，并提供相关证据，一经查实，本社区将立刻删除涉嫌侵权内容，
举报邮箱：cloudbbs@huaweicloud.com
- 点赞
- 收藏
- 关注作者
评论（0）