{% include toc %}
Apache ServiceComb Toolkit is a contract-based microservice development toolkit. Provides the ability to convert and verify contracts, code, and documents, helping users quickly build microservice projects based on popular microservices frameworks and popular programming models, reducing the cost of microservices entry, enabling users to focus on business development, enhance refactoring and development efficiency.
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
Configured in the pom file of the maven project
<plugin> <groupId>org.apache.servicecomb.toolkit</groupId> <artifactId>toolkit-maven-plugin</artifactId> <version>0.2.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> </configuration> </plugin>
# Generating contract, document and microservice project mvn toolkit:generate # Verify code and contract consistency mvn toolkit:verify
Configuration(use default configuration if not set <configuration>
)
example
<plugin> <groupId>org.apache.servicecomb.toolkit</groupId> <artifactId>toolkit-maven-plugin</artifactId> <version>0.2.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
Configuration(use default configuration if not set <configuration>
)
example
<plugin> <groupId>org.apache.servicecomb.toolkit</groupId> <artifactId>toolkit-maven-plugin</artifactId> <version>0.2.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
Configuration
example
<plugin> <groupId>org.apache.servicecomb.toolkit</groupId> <artifactId>toolkit-maven-plugin</artifactId> <version>0.2.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
The executable jar package is located in the toolkit/cli/target/bin directory
$ java -jar toolkit-cli-{version}.jar help
$ java -jar toolkit-cli-{version}.jar codegenerate -m ServiceComb -i swagger.yaml -o ./project -p SpringMVC
codegenerate Command option
$ java -jar toolkit-cli-{version}.jar docgenerate -i swagger.yaml -o ./document
docgenerate Command option
$ java -jar toolkit-cli-{version}.jar checkstyle oas.yaml or $ java -jar toolkit-cli-{version}.jar cs oas.yaml
checkstyle Command argument
$ java -jar toolkit-cli-{version}.jar checkcompatibility left-oas.yaml right-oas.yaml or $ java -jar toolkit-cli-{version}.jar cc left-oas.yaml right-oas.yaml
checkcompatibility Command argument