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_r212526636
########## 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)。 Review comment: It's recommended to use [Swagger Editor](http://editor.swagger.io/#/) to define the APIs. ---------------------------------------------------------------- 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
