title: “Service Contract” lang: en ref: service-contract permalink: /docs/users/service-contract/ excerpt: “Service Contract” last_modified_at: 2017-08-15T15:01:43-04:00 redirect_from:
{% include toc %}
The API of provider and consumer microservice is defined based on OpenAPI regulations.
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.
ServiceComb defines API in a .yaml file. You are advised to use Swagger Editor 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。
The API definition file is located in “resources/microservices” or “resources/applications” directory. The directory structure is as follows:
resources
- microservices
- serviceName #Microservice name
- schemaId.yaml #schema API definition
- applications
- appId #Application ID
- serviceName #Service name
- schemaId.yaml #Schema API definition
swagger: '2.0' info: title: hello version: 1.0.0 x-java-interface: org.apache.servicecomb.samples.common.schema.Hello basePath: /springmvchello produces: - application/json paths: /sayhi: post: operationId: sayHi parameters: - name: name in: query required: true type: string responses: 200: description: returned for a correct result schema: type: string default: description: returned for a default result schema: type: string /sayhello: post: operationId: sayHello parameters: - name: person in: body required: true schema: $ref: "#/definitions/Person" responses: 200: description: returned for a correct result schema: type: string default: description: returned for a default result schema: type: string definitions: Person: type: "object" properties: name: type: "string" description: "person name" xml: name: "Person"
NOTE:
The inplicit API definition is automatically generated by ServiceComb based on the service implementation class.
By using the implicit API definition you can define the implementation class without pre-defining APIs. When the service is started, an API is automatically generated and registered to the service center.
Implicit API definitions can be used for Spring MVC, JAX-RS, and transparent RPC development modes, For details, see Development Style-SpringMVC, Development Stype-JAX-RS and Development Style-Transparent RPC.
When you develop a microservice in transparent RPC mode, the code does not show how you want to define an API, and all generated APIs are POST methods, The input parameters of all the methods will be packaged as a class and transferred as body parameters. Therefore, if you develop providers using implicit APIs, you are advised to choose Spring MVC or JAX-RS mode to obtain complete RESTful statements.