You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@servicecomb.apache.org by li...@apache.org on 2018/08/27 09:03:15 UTC
[incubator-servicecomb-docs] branch master updated (d81d28e ->
9d5aabb)
This is an automated email from the ASF dual-hosted git repository.
liubao pushed a change to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-servicecomb-docs.git.
from d81d28e update java-chassis-reference/en_US/general-development/visit-sc.md
new 97c2463 update java-chassis-reference/en_US/build-provider/swagger-annotation.md
new db3ab8c update java-chassis-reference/en_US/build-provider/listen-address-and-publish-address.md
new 79f9d34 update java-chassis-reference/en_US/build-provider/configuration/parameter-validator.md
new 7091fc3 update java-chassis-reference/en_US/build-provider/protocol/http2.md
new 9d5aabb update java-chassis-reference/en_US/build-provider/definition/isolate-relationship.md
The 5 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
.../configuration/parameter-validator.md | 35 +++---
.../definition/isolate-relationship.md | 36 +++---
.../listen-address-and-publish-address.md | 55 +++++----
.../en_US/build-provider/protocol/http2.md | 19 ++-
.../en_US/build-provider/swagger-annotation.md | 133 ++++++++++-----------
5 files changed, 137 insertions(+), 141 deletions(-)
[incubator-servicecomb-docs] 04/05: update
java-chassis-reference/en_US/build-provider/protocol/http2.md
Posted by li...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
liubao pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-servicecomb-docs.git
commit 7091fc37c6cc9b0477d00449c1b3f094f4dee770
Author: DeanLee <li...@huawei.com>
AuthorDate: Sat Aug 25 16:25:46 2018 +0800
update java-chassis-reference/en_US/build-provider/protocol/http2.md
---
.../en_US/build-provider/protocol/http2.md | 19 +++++++++----------
1 file changed, 9 insertions(+), 10 deletions(-)
diff --git a/java-chassis-reference/en_US/build-provider/protocol/http2.md b/java-chassis-reference/en_US/build-provider/protocol/http2.md
index 1998f13..9b2d542 100644
--- a/java-chassis-reference/en_US/build-provider/protocol/http2.md
+++ b/java-chassis-reference/en_US/build-provider/protocol/http2.md
@@ -1,13 +1,13 @@
-## 场景描述
+## Scene Description
-用户通过简单的配置即可启用Http2进行通信，提高性能。
+Users can enable Http2 to communicate and improve performance through simple configuration.
-## 外部服务通信配置
+## External Service Communication Configuration
-与外部服务通信相关的配置写在microservice.yaml文件中。
+The configuration related to external service communication is written in the microservice.yaml file.
-* 启用h2\(Http2 + TLS\)进行通信
- 服务端在配置服务监听地址时，可以通过在地址后面追加`?sslEnabled=true`开启TLS通信，具体介绍见[使用TLS通信](../../security/tls.md)章节。然后再追加`&protocol=http2`启用h2通信。示例如下：
+* Enable h2\(Http2 + TLS\) for communication
+ When configuring the service listening address, the server can enable TLS communication by appending `?sslEnabled=true` to the address. For details, see the section [Using TLS Communication] (../../security/tls.md). Then add `&protocol=http2` to enable h2 communication. An example is as follows:
```yaml
servicecomb:
@@ -17,8 +17,8 @@
address: 0.0.0.0:7070?sslEnabled=true&protocol=http2
```
-* 启用h2c\(Http2 without TLS\)进行通信
- 服务端在配置服务监听地址时，可以通过在地址后面追加`?protocol=http2`启用h2c通信。示例如下：
+* Enable h2c\(Http2 without TLS\) for communication
+ When the server configures the service listening address, the server can enable h2c communication by appending `?protocol=http2` to the address. An example is as follows:
```yaml
servicecomb:
@@ -27,8 +27,7 @@
highway:
address: 0.0.0.0:7070?protocol=http2
```
-
-* 客户端会通过从服务中心读取服务端地址中的配置来使用http2进行通信。
+* The client will communicate using http2 by reading the configuration in the server address from the service center.
[incubator-servicecomb-docs] 05/05: update
java-chassis-reference/en_US/build-provider/definition/isolate-relationship.md
Posted by li...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
liubao pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-servicecomb-docs.git
commit 9d5aabbb2994bf6dd9e99be3cbcfcdbd5dc86571
Author: DeanLee <li...@huawei.com>
AuthorDate: Sat Aug 25 17:22:09 2018 +0800
update java-chassis-reference/en_US/build-provider/definition/isolate-relationship.md
---
.../definition/isolate-relationship.md | 36 ++++++++++++----------
1 file changed, 19 insertions(+), 17 deletions(-)
diff --git a/java-chassis-reference/en_US/build-provider/definition/isolate-relationship.md b/java-chassis-reference/en_US/build-provider/definition/isolate-relationship.md
index 375bfca..bdffd36 100644
--- a/java-chassis-reference/en_US/build-provider/definition/isolate-relationship.md
+++ b/java-chassis-reference/en_US/build-provider/definition/isolate-relationship.md
@@ -1,30 +1,32 @@
-## 场景描述
+## Scene Description
-进行服务发现的时候，开发者需要了解本微服务能够发现那些其他服务的实例。ServiceComb提供了分层次的实例隔离。
+When doing service discovery, developers need to understand that the microservice can discover instances of those other services. ServiceComb provides hierarchical instance isolation.
-# 微服务实例分层管理
+# Microservices instance hierarchical management
-要了解实例间的隔离层次，首先需要了解ServiceComb定义的一个体系完备的微服务系统结构：
+To understand the isolation level between instances, you first need to understand a well-established microservice system structure defined by ServiceComb:
-在微服务系统结构中，顶层是“项目”，在项目下分为多个租户，租户中包含多个应用，而每个应用又包含多个环境，即测试和生产环境可以分开。在某个特定应用的特定环境中，包含多个微服务，而一个微服务又可以同时存在多个版本。以上，是所有静态元数据的范畴，某个特定服务的特定版本则包含多个在运行时注册上来的微服务实例，因为服务实例的信息在运行时随着系统的伸缩、故障等原因是动态变化的，所以服务实例的路由信息又为动态数据。通过分层管理微服务的这些数据，也就自然而然的实现了实例之间的逻辑隔离。
+In the microservice system structure, the top layer is the “project”, which is divided into multiple tenants under the project. The tenant contains multiple applications, and each application contains multiple environments, that is, the test and production environments can be separated.
+In a particular environment of a particular application, there are multiple microservices, and one microservice can have multiple versions at the same time.
+The above is the scope of all static metadata. A specific version of a particular service contains multiple microservice instances registered at runtime, because the information of the service instance is dynamic at runtime because of system scaling, failure, etc. The change, so the routing information of the service instance is again dynamic data.
+By hierarchically managing these data for microservices, this is natural to achieve logical isolation between instances.
+# isolation level description
-# 隔离层次说明
+ServiceComb supports custom hierarchical configuration to meet the hierarchical management requirements of users. The following is the specific configuration instructions.
-ServiceComb支持自定义分层配置，满足用户的实例分层管理需求，以下是具体配置说明。
+* Application ID
-* 应用ID
+Defined by APPLICATIOIN\_ID, the default value is 'default'. When a microservice discovers an instance, it can only be discovered by consumers under the same APPLICATIOIN\_ID by default.
-通过APPLICATIOIN\_ID来定义，缺省值为default。微服务在发现实例的时候，缺省只能够被相同APPLICATIOIN\_ID下的消费者发现。
+* Domain name
-* Domain名称
+Defined by servicecomb.config.client.domainName, the default value is 'default'. As a micro service provider, it is used to indicate the tenant information that it belongs to. When a microservice finds an instance, it can only be discovered by consumers under the same tenant.
-通过servicecomb.config.client.domainName来定义，缺省值为default。作为微服务提供者，用于表明自身所属租户信息。微服务在发现实例的时候，只能被相同租户下的消费者发现。
+* Data Center Information
-* 数据中心信息
-
-数据中心包括3个属性：servicecomb.datacenter.name， servicecomb.datacenter.region, servicecomb.datacenter.availableZone。数据中心信息不提供隔离能力，微服务可以发现其他数据中心的实例。但是可以通过启用实例亲和性，来优先往指定的区域或者Zone发消息：
+The data center consists of three attributes: servicecomb.datacenter.name, servicecomb.datacenter.region, servicecomb.datacenter.availableZone. Data center information does not provide isolation capabilities, and microservices can discover instances of other data centers. However, you can prioritize sending messages to a specified zone or zone by enabling instance affinity:
```
servicecomb:
@@ -34,11 +36,11 @@ servicecomb:
availableZone: my-Zone
```
-这样配置后，客户端在路由的时候，会优先将请求转发到zone/region都相同的实例，然后是region相同，但zone不相同的实例，都不相同的时候，则按照路由规则选择一个。亲和性不是逻辑隔离，只要实例之间网络是联通的，那么都有可能访问到；如果网络不通，则会访问失败。
+After this configuration, when the client routes, it will forward the request to the same instance with the same zone/region. Then, if the instances with the same region but different zones are different, select one according to the routing rule. Affinity is not logical isolation. As long as the network between the instances is connected, it is possible to access it; if the network is unreachable, the access will fail.
-* 环境信息
+* Environmental information
-在yaml文件里通过service\_description.environment来配置，同时支持通过环境变量SERVICECOMB\_ENV配置，仅支持以下枚举值 development,testing,acceptance,production，缺省值为""\(空\)。微服务在发现实例的时候，缺省只能够被相同environment下的消费者发现。
+It is configured in the yaml file by 'service\_description.environment'. It is also supported by the environment variable 'SERVICECOMB\_ENV'. It only supports the following enumeration : 'development', 'testing', 'acceptance', 'production'. The default value is ""\(empty\). When a microservice discovers an instance, it can only be discovered by consumers under the same environment by default.
```
service_description:
[incubator-servicecomb-docs] 03/05: update
java-chassis-reference/en_US/build-provider/configuration/parameter-validator.md
Posted by li...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
liubao pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-servicecomb-docs.git
commit 79f9d34b520466713e03f08400afd101a7aa0034
Author: DeanLee <li...@huawei.com>
AuthorDate: Sat Aug 25 16:25:33 2018 +0800
update java-chassis-reference/en_US/build-provider/configuration/parameter-validator.md
---
.../configuration/parameter-validator.md | 35 ++++++++++------------
1 file changed, 16 insertions(+), 19 deletions(-)
diff --git a/java-chassis-reference/en_US/build-provider/configuration/parameter-validator.md b/java-chassis-reference/en_US/build-provider/configuration/parameter-validator.md
index 0771a51..3862c99 100644
--- a/java-chassis-reference/en_US/build-provider/configuration/parameter-validator.md
+++ b/java-chassis-reference/en_US/build-provider/configuration/parameter-validator.md
@@ -1,10 +1,10 @@
-## 场景描述
+## Scene Description
-用户在provider端使用参数效验，可以对相应的参数输入要求预先进行设置，在接口实际调用前进行效验处理，达到控制参数输入标准的效果。
+The user uses the parameter validation on the provider client, and can set the corresponding parameter input requirements in advance, and perform the effect processing before the interface is actually called to achieve the effect of the control parameter input standard.
-## 配置说明
+## Configuration instructions
-* 添加swagger-invocation-validator的pom依赖：
+* Add the pom dependency of swagger-invocation-validator:
```xml
<dependency>
@@ -13,12 +13,11 @@
</dependency>
```
-* 在需要验证的代码上按照JSR 349规范添加验证器注解，如@NotNull，@Min，@Max等。
+* Add validator annotations to the code that requires validation according to the JSR 349 specification, such as @NotNull, @Min, @Max, etc.
-## 示例代码
-
-* 接口参数验证
+## Sample Code
+* Interface parameter verification
```java
@RestSchema(schemaId = "validator")
@Path("/validator")
@@ -48,9 +47,9 @@ public class Validator {
}
```
-* bean类验证
+* bean class validation
-需要在传入的Student对象前加@Valid，如上图sayHello\(@Valid Student student\)方法。
+You need to add @Valid in front of the incoming Student object, as shown in the figure above, sayHello\(@Valid Student student\).
```java
public class Student {
@@ -77,18 +76,17 @@ public class Student {
}
}
```
+## Custom return exception
-## 自定义返回异常
-
-* 默认的参数效验器ParameterValidator已经实现了接口ProducerInvokeExtension，按照JSR 349规范处理所需的参数验证。
+* The default parameter validation parameter ParameterValidator has implemented the interface ProducerInvokeExtension to handle the required parameter validation in accordance with the JSR 349 specification.
- 如果任何参数验证失败，缺省错误是BAD\_REQUEST\(400, "Bad Request"\)。
+ If any parameter validation fails, the default error is BAD\_REQUEST\(400, "Bad Request"\).
- 返回错误支持自定义扩展，使用SPI机制。
+ Return error support for custom extensions, using the SPI mechanism.
-* 可以通过实现接口ExceptionToResponseConverter来自定义返回的错误信息，以ConstraintViolationExceptionToResponseConverter为例。
+* You can customize the returned error information by implementing the interface ExceptionToResponseConverter, taking the ConstraintViolationExceptionToResponseConverter as an example.
- 1. 实现ExceptionToResponseConverter接口，重写方法，其中getOrder方法的返回结果表示该验证器的优先级，值越小优先级越高。
+ 1. Implement the ExceptionToResponseConverter interface, override the method, where the return result of the getOrder method indicates the priority of the validator. The smaller the value, the higher the priority.
```java
public class ConstraintViolationExceptionToResponseConverter
@@ -110,7 +108,6 @@ public class Student {
}
```
- 2. 在META-INF下的services文件夹增加一个文件，以所实现接口x.x.x.ExceptionToResponseConverter\(带包名\)为名，以具体实现类x.x.x.ConstraintViolationExceptionToResponseConverter\(带包名\)为内容。
-
+ 2. Add a file in the services folder under META-INF, with the implementation interface x.x.x.ExceptionToResponseConverter\ (with package name\) as the name, and the concrete implementation class x.x.x.ConstraintViolationExceptionToResponseConverter\ (with package name\) as the content.
[incubator-servicecomb-docs] 02/05: update
java-chassis-reference/en_US/build-provider/listen-address-and-publish-address.md
Posted by li...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
liubao pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-servicecomb-docs.git
commit db3ab8c4f1fa24cad7a745348f39e67b592bb52a
Author: DeanLee <li...@huawei.com>
AuthorDate: Sat Aug 25 14:53:47 2018 +0800
update java-chassis-reference/en_US/build-provider/listen-address-and-publish-address.md
---
.../listen-address-and-publish-address.md | 55 +++++++++++-----------
1 file changed, 27 insertions(+), 28 deletions(-)
diff --git a/java-chassis-reference/en_US/build-provider/listen-address-and-publish-address.md b/java-chassis-reference/en_US/build-provider/listen-address-and-publish-address.md
index a31cd66..7dab522 100644
--- a/java-chassis-reference/en_US/build-provider/listen-address-and-publish-address.md
+++ b/java-chassis-reference/en_US/build-provider/listen-address-and-publish-address.md
@@ -1,45 +1,44 @@
-# 服务监听地址和发布地址
+# Service listening address and publishing address
-### 概念阐述
+### Concept Description
-在JavaChassis中，服务的监听地址和发布地址是两个独立的概念，可以独立配置：
+In JavaChassis, the listening address and publishing address of the service are two independent concepts that can be configured independently:
-* 监听地址：指微服务实例启动时监听的地址。该配置项决定了可以通过哪些IP访问此服务。
-* 发布地址：指微服务实例注册到服务中心的地址。其他的微服务实例会通过服务中心获取此实例的信息，根据发布地址访问此服务实例，所以该配置项决定了其他服务实际上会使用哪个IP访问此服务。
+* Listening address: refers to the address that the microservice instance listens to when it starts. This configuration item determines which IPs can be accessed by this IP.
+* Publish Address: refers to the address where the microservice instance is registered to the service center. Other microservice instances will obtain information about this instance through the service center and access the service instance based on the publication address, so this configuration item determines which IP other services actually use to access the service.
-### 场景描述
+### Scene Description
-用户通过配置服务的监听地址和发布地址来确定服务实例监听的IP和其他服务实例访问本实例时请求的IP。
+The user determines the IP address that the service instance listens to and the IP address requested by other service instances when accessing the instance by configuring the listening address and the publishing address of the service.
-### 配置说明
+### Configuration instructions
-服务监听地址的配置项是`servicecomb.rest.address`和`servicecomb.highway.address`，分别对应rest传输方式和highway传输方式的监听地址。两者的配置规则相同，以下仅以`servicecomb.rest.address`作为说明。
-服务发布地址的配置项是`servicecomb.service.publishAddress`，该地址**可以不配置**。不配置此项时JavaChassis会根据特定的规则选取发布地址。
+The configuration items of the service listening address are `servicecomb.rest.address` and `servicecomb.highway.address`, which respectively correspond to the listening address of the rest transmission mode and the highway transmission mode. The configuration rules for both are the same. The following only uses `servicecomb.rest.address` as an explanation.
+The configuration item of the service publishing address is `servicecomb.service.publishAddress`, which can be configured without **. When this item is not configured, JavaChassis will select the publishing address according to the specific rules.
-**表1 服务发布地址生效规则**
+**Table 1 Service Release Address Effective Rules**
-| 规则编号 | 监听地址配置 | 发布地址配置 | 实际生效的发布地址 |
+| Rule Number | Listening Address Configuration | Publishing Address Configuration | Effective Delivery Address |
| :--- | :--- | :--- | :--- |
| 1 | 127.0.0.1 | - | 127.0.0.1 |
-| 2 | 0.0.0.0 | - | 选取一张网卡的IP地址作为发布地址。<br/>要求该地址不能是通配符地址、回环地址或广播地址 |
-| 3 | 具体IP | - | 与监听地址一致 |
-| 4 | * | 具体IP | 与发布地址配置项一致 |
-| 5 | * | "{网卡名}" | 指定网卡名的IP，注意需要加上引号和括号 |
-
-> **说明：**
-> - 服务实例实际监听的地址始终与监听地址配置项保持一致。
-> - 使用网卡名配置发布地址时，要求使用双引号包裹住网卡名占位符，否则会造成解析配置报错。
-> - 网卡名必须是主机存在的网卡。
-
-### 示例代码
-
-microservice.yaml文件的配置示例如下：
+| 2 | 0.0.0.0 | - | Select the IP address of a network card as the publishing address. Require that the address cannot be a wildcard address, loopback address, or broadcast address |
+| 3 | Specific IP | - | Consistent with the listening address |
+| 4 | * | Specific IP | Consistent with the published address configuration item |
+| 5 | * | "{NIC name}" | Specify the IP of the NIC name, note the need to put quotation marks and brackets |
+> **Note: **
+> - The address actually listened to by the service instance is always consistent with the listening address configuration item.
+> - When using the NIC name to configure the publishing address, you need to use double quotation marks to wrap the NIC name placeholder, otherwise the parsing configuration will be reported.
+> - The NIC name must be the NIC that the host exists.
+
+### Sample Code
+
+An example of the configuration of the microservice.yaml file is as follows:
```yaml
servicecomb:
service:
- publishAddress: "{eth0}" # 注册到服务中心的发布地址会是eth0网卡的IP
+ publishAddress: "{eth0}" # The publishing address, registered to the service center, will be the IP of the eth0 network card
rest:
- address: 0.0.0.0:8080 # 监听主机的全部网卡IP
+ address: 0.0.0.0:8080 # Monitor all NIC IPs of the hos
highway:
- address: 0.0.0.0:7070 # 监听主机的全部网卡IP
+ address: 0.0.0.0:7070 # Listen to all NIC IPs of the host
```
\ No newline at end of file
[incubator-servicecomb-docs] 01/05: update
java-chassis-reference/en_US/build-provider/swagger-annotation.md
Posted by li...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
liubao pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-servicecomb-docs.git
commit 97c24631be85409acb34ab32c4a90441c58c8e26
Author: DeanLee <li...@huawei.com>
AuthorDate: Sat Aug 25 14:28:51 2018 +0800
update java-chassis-reference/en_US/build-provider/swagger-annotation.md
---
.../en_US/build-provider/swagger-annotation.md | 133 ++++++++++-----------
1 file changed, 66 insertions(+), 67 deletions(-)
diff --git a/java-chassis-reference/en_US/build-provider/swagger-annotation.md b/java-chassis-reference/en_US/build-provider/swagger-annotation.md
index 49d9f1e..24a7bfb 100644
--- a/java-chassis-reference/en_US/build-provider/swagger-annotation.md
+++ b/java-chassis-reference/en_US/build-provider/swagger-annotation.md
@@ -1,110 +1,109 @@
-# 使用 Swagger 注解
+# Using Swagger annotations
-## 概念阐述
+## Concept Description
-Swagger提供了一套注解用于描述接口契约，用户使用注解，可以在代码中增加对于契约的描述信息。ServiceComb支持其中的部分注解。
+Swagger provides a set of annotations for describing interface contracts. Users can use annotations to add descriptions of contracts to their code. ServiceComb supports part of these annotations.
-## 场景描述
+## Scene Description
-通过使用注解描述接口契约，用户可以利用ServiceComb的Swagger契约生成功能自动生成符合要求的契约文件，而无须手工编写和修改契约，能够有效提高开发效率。
+By using annotations to describe interface contracts, users can use ServiceComb's Swagger contract generation function to automatically generate contract documents that meet the requirements without having to manually write and modify contracts, which can effectively improve development efficiency.
-## 配置说明
+## Configuration instructions
-关于Swagger注解的含义，可以在[Swagger注解文档](https://github.com/swagger-api/swagger-core/wiki/Annotations-1.5.X)中找到官方说明。您可以对照该官方文档与本说明来了解如何在ServiceComb框架下使用注解指定Swagger契约的各项属性。
+The official description can be found in the [Swagger Annotation Document] (https://github.com/swagger-api/swagger-core/wiki/Annotations-1.5.X). You can refer to the official documentation and this guide to learn how to use annotations to specify the properties of a Swagger contract under the ServiceComb framework.
-在ServiceComb中，Swagger注解不是必须使用的。当用户使用SpringMVC和JAX-RS的注解来标注微服务方法时，ServiceComb可以根据这些注解的值推断出各微服务方法的契约信息。
+In ServiceComb, Swagger annotations are not required. When a user uses SpringMVC and JAX-RS annotations to annotate microservice methods, ServiceComb can infer the contract information for each microservice method based on the values of these annotations.
### `@Api`
-> `@Api`作用于类级别，在Swagger官方描述中是用于将一个Class标注为一个Swagger资源。但该注解在ServiceComb中不是必须的，ServiceComb可以根据`@RestSchema`和`@RpcSchema`确定需要从哪些类中解析出Swagger契约。<br/>
-ServiceComb当前支持的属性只有tags。
+> `@Api` acts at the class level and is used to mark a Class as a Swagger resource in the official Swagger description. However, this annotation is not required in ServiceComb. ServiceComb can determine which classes need to parse the Swagger contract based on `@RestSchema` and `@RpcSchema`. The only attributes currently supported by ServiceComb are tags.
-| 属性 | 类型 | 说明 |
+| Attribute | Type | Description |
| :--- | :------ | :--- |
-| tags | string | 设置当前Class下定义的operation的默认tag值 |
+Tags | string | set the default tag value of the operation defined under the current Class |
### `@SwaggerDefinition`
-> 作用于类级别，用于定义一个Swagger资源中的信息。
+> Acts at the class level to define information in a Swagger resource.
-| 属性 | 类型 | 说明 |
+| Attribute | Type | Description |
| :--- | :------ | :--- |
-| info.title | string | 契约文件标题 |
-| info.description | string | 描述信息 |
-| info.version | string | 契约版本号 |
-| info.termsOfService | string | 服务条款 |
-| info.contact | string | 联系信息，包含name、email、url属性 |
-| info.license | string | 许可证信息，包含name、url属性 |
-| info.extensions | string | 扩展信息 |
-| consumes | string | 接收的请求格式 |
-| produces | string | 返回的应答格式 |
-| schemes | SwaggerDefinition.Scheme | 可选值有`HTTP/HTTPS/WS/WSS/DEFAULT` |
-| tags | `@Tag` | Tag定义，@Tag包含name、description、externalDocs三个属性 |
-| externalDocs | `@externalDocs` | 外部说明文档链接，包含value、url两个属性 |
+| info.title | string | Contract Document Title |
+| info.description | string | Description |
+| info.version | string | contract version number |
+| info.termsOfService | string | Terms of Service |
+| info.contact | string | Contact information, including name, email, url attributes |
+| info.license | string | License information, including name, url attribute |
+| info.extensions | string | Extended Information |
+| consumes | string | Receive Request Format |
+| produces | string | returned response format |
+| schemes | SwaggerDefinition.Scheme | Optional values are `HTTP/HTTPS/WS/WSS/DEFAULT` |
+| tags | `@Tag` | Tag definition, @Tag contains three attributes: name, description, externalDocs |
+| externalDocs | `@externalDocs` | External documentation links, including values and urls |
### `@ApiOperation`
-> 作用于方法级别，用于描述一个Swagger operation。
+> Acts at the method level to describe a Swagger operation.
-| 属性 | 类型 | 说明 |
+| Attribute | Type | Description |
| :--- | :------ | :--- |
-| value | string | 方法的简要说明，对应于Swagger契约operation的`summary`字段 |
-| notes | string | 详细信息，对应于Swagger契约operation的`description`字段 |
-| tags | string | 标注operation的标签 |
-| code | int | 响应消息的HTTP状态码 |
-| response | Class<?> | 方法返回值类型 |
-| responseContainer | string | 包装返回值的容器类型，可选值为`List`、`Set`、`Map` |
-| responseHeaders | `@ResponseHeader` | 响应消息的HTTP头，ServiceComb支持的属性值为`name`、`response`、`responseContainer` |
-| consumes | string | 指定请求体的数据格式 |
-| produces | string | 指定响应体的数据格式 |
-| protocols | string | 设置可用的协议（schemes），可选值有`http`、`https`、`ws`、`wss`，逗号分隔 |
-| httpMethod | string | 设置HTTP方法 |
+| value | string | A brief description of the method, corresponding to the `summary` field of the Swagger contract operation |
+| notes | string | Details, corresponding to the `description` field of the Swagger contract operation |
+Tags | string | label operation label |
+| code | int | HTTP status code for response messages |
+| response | Class<?> | Method return value type |
+responseContainer | string | The container type that wraps the return value. The optional values are `List`, `Set`, `Map` |
+| ResponseHeaders | `@ ResponseHeader` | HTTP response message header, ServiceComb support attribute value of` name`, `response`,` responseContainer` |
+| Consumes | string | specified data format request body |
+| Produces | string | body in response to the data format specified |
+| Protocols | string | the available protocol (schemes), possible values are `http`,` https`, `ws`,` wss`, separated by commas |
+| httpMethod | string | Set HTTP method |
### `@ApiImplicitParam`
-> 作用于方法级别，用于说明Swagger文档中operation的参数的属性。
+> Acts at the method level, which is used to describe the properties of the parameters of the operation in the Swagger document.
>
-> **注意**：ServiceComb可以根据代码和SpringMVC、JAX-RS的注解自动推断出参数名称。如果`@ApiImplicitParam`配置的参数名称与自动推断的参数名不同，则则该注解配置的参数将被作为一个新的参数加入到注解所在的operation中；否则将覆盖同名参数的属性。
+> **Note**: ServiceComb can automatically infer parameter names based on code and SpringMVC, JAX-RS annotations. If the parameter name of the `@ApiImplicitParam` configuration is different from the automatically inferred parameter name, then the parameter of the annotation configuration will be added as a new parameter to the operation in which the annotation is located; otherwise, the property of the parameter with the same name will be overwritten.
-| 属性 | 类型 | 说明 |
+| Attribute | Type | Description |
| :--- | :------ | :--- |
-| name | string | 参数名称 |
-| value | string | 参数说明 |
-| required | boolean | 是否是必填参数 |
-| dataType | string | 参数数据类型 |
-| paramType | string | 参数位置，有效的可选值为path/query/body/header/form |
-| allowableValues | string | 参数的有效值范围 |
-| allowEmptyValue | boolean | 是否允许空值 |
-| allowMultiple | boolean | 是否允许多个值（若为true，则可以将参数作为数组） |
-| collectionFormat | string | 以何种格式指定参数数组，当前ServiceComb支持的值为`csv/multi` |
-| defaultValue | string | 参数默认值 |
-| example | string | 一个非body参数的示例值 |
-| format | string | 允许用户自定义数据格式，详情参见Swagger官方文档 |
+| name | string | parameter name |
+| value | string | Parameter Description |
+| required | boolean | Is this a required parameter |
+| dataType | string | Parameter Data Type |
+| paramType | string | parameter location, valid optional value is path/query/body/header/form |
+| allowableValues | string | Range of valid values for |
+| allowEmptyValue | boolean | Whether to allow null values |
+| allowMultiple | boolean | Whether to allow multiple values (if true, parameters can be used as an array) |
+| collectionFormat | string | In which format the parameter array is specified, the current ServiceComb support value is `csv/multi` |
+| defaultValue | string | parameter default |
+| example | string | Example value for a non-body parameter |
+| format | string | Allows users to customize the data format. See the Swagger official documentation for details.
### `@ApiImplicitParams`
-> `@ApiImplicitParams`作用于方法、类级别，用于批量指定多个`@ApiImplicitParam`。
+> `@ApiImplicitParams` acts on methods, class levels, and is used to batch specify multiple `@ApiImplicitParam`.
-| 属性 | 类型 | 说明 |
+| Attribute | Type | Description |
| :--- | :------ | :--- |
-| value | `@ApiImplicitParam` | 参数定义 |
+| value | `@ApiImplicitParam` | Parameter definition |
### `@ApiResponse`
-> 用于描述返回消息的HTTP状态码所表达的含义。通常`@ApiOperation`可以表示一个正常情况返回消息的HTTP状态码，其他情形下的HTTP状态码由本注解描述。根据Swagger官方文档的描述，本注解不应该直接用于方法级别，而应该被包含在`@ApiResponses`中。
+> Used to describe the meaning of the HTTP status code of the returned message. Usually `@ApiOperation` can represent the HTTP status code of a normal return message. In other cases, the HTTP status code is described by this note. According to the Swagger official documentation, this annotation should not be used directly at the method level, but should be included in `@ApiResponses`.
-| 属性 | 类型 | 说明 |
+| Attribute | Type | Description |
| :--- | :------ | :--- |
-| code | int | 返回消息的HTTP状态码 |
-| message | string | 返回值的说明信息 |
-| response | Class<?> | 返回值的类型 |
-| responseContainer | string | 返回值的包装容器，可选值为`List/Set/Map` |
-| responseHeaders | @ResponseHeader | 描述一组返回消息的HTTP头，ServiceComb支持的`@ResponseHeader`的属性有`name`、`description`、`response`、`responseContainer` |
+| code | int | Return the HTTP status code of the message |
+| message | string | Description of the return value |
+| response | Class<?> | Type of return value |
+| responseContainer | string | The wrapper for the return value, with an optional value of `List/Set/Map` |
+| responseHeaders | @ResponseHeader | Describes a set of HTTP headers that return messages. The properties of `@ResponseHeader` supported by ServiceComb are `name`, `description`, `response`, `responseContainer` |
### `@ApiResponses`
-> 作用于方法、类级别，用于指定和说明一组返回值。
+> Acts on methods, class levels, to specify and specify a set of return values.
-| 属性 | 类型 | 说明 |
+| Attribute | Type | Description |
| :--- | :------ | :--- |
-| value | `@ApiResponse` | 返回消息说明 |
+| value | `@ApiResponse` | Return to message description |
\ No newline at end of file