Toolkit | 中文 Build StatusCoverage StatusLicenseQuality Gate Status Gitter

Apache ServiceComb Toolkit is a contract-based microservice development toolkit

1 Introduction

1.1 Conceptions

image

1.2 Features

1.3 Applicable Scene

2 Design

2.1 Architecture

image

2.2 Working Principle

image

3 Quick Start

3.1 Build tool and plugins from source

Build environment requirements

# Get the latest source code for toolkit from github
$ git clone https://github.com/apache/servicecomb-toolkit.git
$ cd toolkit

# Build package
$ mvn clean install

3.2 Use the toolkit-maven-plugin plugin

3.2.1 configuration

Configured in the pom file of the maven project

<plugin>
    <groupId>org.apache.servicecomb.toolkit</groupId>
    <artifactId>toolkit-maven-plugin</artifactId>
    <version>0.3.0-SNAPSHOT</version>
    <configuration>
        <!-- Set to 'code' to resolve the current project. Set to 'contract' to resolve the contract file for the specified path.If not set, the default is 'code' -->
        <sourceType>code</sourceType>
        <!-- The type of the contract file is generated. If it is not set, the default is 'yaml' -->
        <contractFileType>yaml</contractFileType>
        <!-- The type of the generated document. If not set, the default is 'html' -->
        <documentType>html</documentType>
        <!-- The root directory to save microservice project,contract file and document. If it is not set, the default is the 'target' under the directory where the command is run -->
        <outputDirectory>./target</outputDirectory>
        <!-- Input contract file path. Valid when sourceType is set to 'contract', must be set -->
        <contractLocation>./contract</contractLocation>
        <!-- Checked contract file path. Valid when sourceType is set to 'contract', must be set -->
        <sourceContractPath>./target/contract</sourceContractPath>
        <!-- Sample contract file path, must be set -->
        <destinationContractPath>./contract</destinationContractPath>
        <!-- Generated microservice project configuration -->
        <service>
            <!-- Microservice type,can generated 'provider/consumer/all',the default is 'all' -->
            <serviceType>all</serviceType>
            <!-- Microservice project 'groupid',optional,the default is 'domain.orgnization.project' -->
            <groupId>domain.orgnization.project</groupId>
            <!-- Microservice project 'artifactId',optional,the default is 'sample' -->
            <artifactId>sample</artifactId>
            <!-- Microservice project 'artifactVersion',optional,the default is '0.1.0-SNAPSHOT' -->
            <artifactVersion>0.1.0-SNAPSHOT</artifactVersion>
            <!-- Microservice project 'packageName',optional,the default is 'domain.orgnization.project.sample' -->
            <packageName>domain.orgnization.project.sample</packageName>
        </service>
        <!-- Specify additional attribute values that can be referenced by the mustache template.Only used when plugin goal is generate -->
        <additionalProperties>
            <prop1>value</prop1>
            <prop2>value</prop2>
            ...
            <propN>value</propN>
        </additionalProperties>
    </configuration>
</plugin>

3.2.2 Command

# Generating contract, document and microservice project
mvn toolkit:generate

# Verify code and contract consistency
mvn toolkit:verify

3.2.2.1 Extract the microservice project, OpenAPI contract file and document from the code

Configuration(use default configuration if not set <configuration>)

example

<plugin>
    <groupId>org.apache.servicecomb.toolkit</groupId>
    <artifactId>toolkit-maven-plugin</artifactId>
    <version>0.3.0-SNAPSHOT</version>
    <configuration>
        <!-- Set to 'code' to resolve the current project. Set to 'contract' to resolve the contract file for the specified path.If not set, the default is 'code' -->
        <sourceType>code</sourceType>
        <!-- The root directory to save contract file and document. If it is not set, the default is the 'target' under the directory where the command is run -->
        <outputDirectory>./target</outputDirectory>
        <!-- Generated microservice project configuration -->
        <service>
            <!-- Microservice type,can generated 'provider/consumer/all',the default is 'all' -->
            <serviceType>all</serviceType>
        </service>
    </configuration>
</plugin>

Run in shell

mvn toolkit:generate

When generating contracts from code,support for identifying restful interfaces written by the following annotations (class level)

RestController, RestSchema, RpcSchema, RequestMapping

When generating contracts from code,the restful interface method access modifier must be specified as public

3.2.2.2 Generate the microservice project and document from contract

Configuration(use default configuration if not set <configuration>)

example

<plugin>
    <groupId>org.apache.servicecomb.toolkit</groupId>
    <artifactId>toolkit-maven-plugin</artifactId>
    <version>0.3.0-SNAPSHOT</version>
    <configuration>
        <!-- Set to 'code' to resolve the current project. Set to 'contract' to resolve the contract file for the specified path.If not set, the default is 'code' -->
        <sourceType>contract</sourceType>
        <!-- The root directory to save contract file and document. If it is not set, the default is the 'target' under the directory where the command is run -->
        <outputDirectory>./target</outputDirectory>
        <!-- Input contract file path. Valid when sourceType is set to 'contract', must be set -->
        <contractLocation>./contract</contractLocation>
        <!-- Generated microservice project configuration -->
        <service>
            <!-- Microservice type,can generated 'provider/consumer/all',the default is 'all' -->
            <serviceType>provider</serviceType>
        </service>
    </configuration>
</plugin>

Run in shell

mvn toolkit:generate

3.2.2.3 Contract verify

Configuration

example

<plugin>
    <groupId>org.apache.servicecomb.toolkit</groupId>
    <artifactId>toolkit-maven-plugin</artifactId>
    <version>0.3.0-SNAPSHOT</version>
    <configuration>
        <!-- Set to 'code' to resolve the current project. Set to 'contract' to resolve the contract file for the specified path.If not set, the default is 'code' -->
        <sourceType>code</sourceType>
        <!-- Sample contract file path, must be set -->
        <destinationContractPath>./contract</destinationContractPath>
    </configuration>
</plugin>

Run in shell

mvn toolkit:verify

3.3 Use the toolkit cli

All the examples below are introduced through cli.sh for Linux environment

$ ./cli.sh help

3.3.1 Service contract generation microservice project

$ ./cli.sh codegenerate -m ServiceComb -i swagger.yaml -o ./project -p SpringMVC

codegenerate Command option

  • -m, --microservice-framework. Specify microservices framework, now supports ServiceComb.
    e.g.:-m ServiceComb
  • -p, --programming-model. Specify programming model, optional JAX-RS, POJO, SpringMVC, SpringBoot.
    e.g.:-p SpringMvc
  • -i, --input. Specifies contract files that follow the OpenAPI specification, supports yaml and json formats, and supports specifying local and network files.
    e.g.:-i http://petstore.swagger.io/v2/swagger.json
  • -o, --output. Generated project code output path.
    e.g.:-o ./project
  • --group-id. Specify the group id of the generated project.
    e.g.:--group-id com.demo
  • --artifact-id. Specify the artifact id of the generated project.
    e.g.:--artifact-id springmvc-example
  • --artifact-version. Specify the artifact version of the generated project.
    e.g.:--artifact-version 1.0.0
  • --api-package : Specify the api package of the generated project.
    e.g.:--api-package com.demo.api
  • --model-package : Specify the model package of the generated project.
    e.g.:--model-package com.demo.model
  • -t, --service-type : Specify microservice type of generated microservice project. optional value is provider,consumer,all
    e.g.:--service-type provider
  • --properties : Specify additional attribute values that can be referenced by the mustache template e.g.:--properties applicationId=app,providerServiceId=provider

3.3.2 Service contract generation document

$ ./cli.sh docgenerate -i swagger.yaml -o ./document

docgenerate Command option

  • -i, --input. Specifies contract files that follow the OpenAPI specification, supports yaml and json formats, and supports specifying local and network files. e.g:-i http://petstore.swagger.io/v2/swagger.json
  • -o, --output. Document output path. e.g:-o ./document
  • -f, --format. Specifies the output document format, now supports swagger-ui e.g:-f swagger-ui

3.3.3 Service contract style checking

$ ./cli.sh checkstyle -r style-check-rules.yaml -f oas.yaml
or
$ ./cli.sh cs -r style-check-rules.yaml -f oas.yaml

checkstyle Command argument

  • -r, --rules-file. Rules properties file.
  • -f, --file. OpenAPI v3 spec yaml.

See style check rules

3.3.4 Service contract compatibility checking

$ ./cli.sh checkcompatibility left-oas.yaml right-oas.yaml
or
$ ./cli.sh cc left-oas.yaml right-oas.yaml

checkcompatibility Command argument

  • <files> Two OpenAPI v3 spec yaml file

See compatibilty check rules

3.4 Use case

some example of using plugin can be found here

4 Contact us

5 Contribute

PR: Pull request