_users/define-service-contract.md

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:

/theme-setup/

{% include toc %}

Concept Description

The API of provider and consumer microservice is defined based on OpenAPI regulations.

Scenario

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 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

Sample Code

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：

According to Swagger specifications, the path specified by basePath should contain the webroot of the web server.
info.x-java-interface requires a specific API path. Set it as needed.

Implicit API Definition

Concept Description

　　The inplicit API definition is automatically generated by ServiceComb based on the service implementation class.

Scenario

　　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.

Involved API

　　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.