crystaldust commented on a change in pull request #43: Migration build-provider from web repo URL: https://github.com/apache/incubator-servicecomb-docs/pull/43#discussion_r212526847
########## File path: java-chassis-reference/en_US/build-provider/define-contract.md ########## @@ -1,49 +1,33 @@ -# 定义服务契约 +# Service Contract Definition `` -## 概念阐述 +## Concept Description -服务契约，指基于OpenAPI规范的微服务接口契约，是服务端与消费端对于接口的定义。java chassis提供了两种方式定义契约：code first和contract first。 -* code first +The API of provider and consumer microservice is defined based on OpenAPI regulations. -producer使用Jax-RS或SpringMVC的RESTful annotation声明接口的输入、输出参数，或者再配合OpenAPI的annotation，增加人类可读的信息，比如样例代码、文本描述等等；ServiceComb引擎启动时，根据这些annotation生成契约描述，并自动上传到服务中心。producer也可以使用透明RPC方式开发，但是因为没有任何RESTful的annotation指导如何生成契约，所以此时自动生成的契约非常的不RESTful化，不建议使用。 -consumer使用透明RPC或RestTemplate进行调用。 -code first的开发模式下，开发人员，不必手写契约。 +## Scenario -* contract first +The API definition decouples providers and consumers, which allows the two parties to use different programming languages, Providers provide services and consumers call them based on the API definition. -此场景下，不使用框架自动生成的契约，而是直接使用开发人员提供的契约文件，这需要由开发人员保证契约与代码的一致性。 +## Explicit API Definition -## 场景描述 +### Configuration -服务契约用于服务端和消费端的解耦，服务端围绕契约进行服务的实现，消费端根据契约进行服务的调用，可支持服务端和消费端采用不同的编程语言实现。 +ServiceComb defines API in a .yaml file. You are advised to use [Swagger Editor](http://editor.swagger.io/#/) to write an API definition. This tool can check syntax and automaticlly generate an API document. For details about the API definition file format, see [ Official OpenAPI documentation](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md)。 -> _**说明:**_ -> 服务提供者在启动时会将接口契约注册到服务中心，可供服务消费者下载使用。接口契约是微服务-版本级别的信息，当多个微服务实例启动时，有一个实例将契约注册到服务中心后，服务中心就不会再用后来者注册的契约信息覆盖已有的契约。因此，仅修改服务提供者的接口信息不会让服务中心存储的契约发生变化，对于服务消费者而言，获取到的接口信息依然是旧的。若要更新服务中心中的接口契约，可以选择升级微服务版本号，或者删除已有的微服务信息（后者不建议在生产环境使用）。 +The API definition file is located in "resources/microservices" or "resources/applications" directory. The directory structure is as follows: -## 配置说明 - -ServiceComb使用yaml文件格式定义服务契约，推荐使用[Swagger Editor](http://editor.swagger.io/#/)工具来编写契约，可检查语法格式及自动生成API文档。详细的契约文件格式请参考[OpenAPI官方文档](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md)。 - -契约文件放置在"resources/microservices"或者"resources/application"目录下，目录结构如下所示。 - -```yaml +```txt resources - - microservices - - serviceName #微服务名 - - schemaId.yaml #schema接口的契约 - - applications - - appId #应用ID - - serviceName #微服务名 - - schemaId.yaml #schema接口的契约 + - microservices + - serviceName #Microservice name + - schemaId.yaml #schema API definition + - applications + - appId #Application ID + - serviceName #Service name + - schemaId.yaml #Schema API definition Review comment: #Schema ID即可 ---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: [email protected] With regards, Apache Git Services
