By Ke Ran (Xieying)
Swagger is a standard and complete frontend framework for generating, describing, calling, and visualizing RESTful Web services. The Swagger specification has gradually developed into the OpenAPI specification.
Springfox is a generation framework for Swagger description files that integrates Swagger and is implemented based on Spring MVC and Spring Webflux. It defines some annotations to describe interfaces. After using these annotations, Springfox generates Swagger description files automatically, which enables Swagger to display and call interfaces.
Dubbo Admin provides the interface testing feature but lacks the interface description document. Therefore, this test feature is suitable for interface developers to test interfaces. Others that want to use this feature must understand the interface information by reading the documentation written by the interface developers or by other means.
Does Dubbo have a tool combining document display and testing features (like Swagger or Springfox) that can provide the interface directly to the caller without writing a document?
Some research has been conducted, and some similar tools have been found:
They all have one thing in common, which is turning the provider into a web project. Some providers are started by loading the web container or even connected with web engineering. These providers will not affect the use of tools.
However, for non-web providers, is it necessary to turn them into web projects for the sake of documentation and introduce web framework dependencies such as Spring MVC? Is it necessary to delete the references and annotations in the code of the provider when packaging the production environment? Is there a simpler way?
OpenAPI does not have RPC specifications. Swagger is the implementation of OpenAPI, so it does not support RPC-related calls either. Springfox is a RESTful API tool implemented through Swagger, while RESTful API is based on the web and cannot be used by Dubbo directly. Therefore, Dubbo implements the features of Swagger itself:
Today, with the release of Dubbo-Api-Docs, I am pleased to announce that Dubbo users can also enjoy an experience similar to Swagger.
Dubbo-Api-Docs is a tool for displaying Dubbo interface documentation and testing the interfaces.
There are two main steps to use Dubbo-Api-Docs:
After these two steps, users can enjoy an experience similar to Swagger and disable the scanning of Dubbo-Api-Docs in the production environment.
Currently, Dubbo-Api-Docs gets the interface list of the service by connecting directly to the service node. The interface can be tested by connecting directly to the service node or through the registry. In the future, the service list can also be obtained through the registry. New functional supports will also be added according to the Dubbo upgrade plan and the needs of the community.
After the service provider is started, Dubbo-Api-Docs scans the document annotations, caches the processing results, and adds some Dubbo provider interfaces related to Dubbo-Api-Docs. Cached data may be stored in the Dubbo metadata center in the future.
<dependency>
<groupId>org.apache.dubbo</groupId>
<artifactId>dubbo-api-docs-annotations</artifactId>
<version>${dubbo-version}
org.apache.dubbodubbo-api-docs-core${dubbo-version}</version>
</dependency>
org.apache.dubbodubbo-api-docs-core${dubbo-version}</ version>
</ dependency>
dubbo-api-docs-annotations
to the project.dubbo-api-docs-core
to the Dubbo provider project@EnableDubboApiDocs
to the project startup class (the class labeled with @SpringBootApplication
) or the configuration class (the class labeled with @Configuration
) of the provider project to enable the Dubbo-Api-Docs features.It is recommended that a configuration class be created separately to avoid the occupancy of resources in the production environment and enable Dubbo-Api-Docs and used with the annotation @Profile("dev")
.
Dubbo-Api-Docs consumes a little more CPU resources and uses a few memories for caching only when the project starts. The cached data may be stored in the metadata center in the future.
git clone -b 2.7.x https://github.com/apache/dubbo-spi-extensions.git
Enter the dubbo-spi-extensions/dubbo-api-docs/dubbo-api-docs-examples
directory
The dubbo-api-docs-examples
have two submodules:
examples-api
: A jar package containing the service interfaces and interface parameter Beanexamples-provider
: The provider server, including implementations of Spring Boot initiator and services.Next, introduce the Dubbo-Api-Docs to these two submodules:
examples-api:
Introduce Maven:
<dependency>
<groupId>org.apache.dubbo</groupId>
<artifactId>dubbo-api-docs-annotations</artifactId>
<version>2.7.8</version>
</dependency>
org.apache.dubbo.apidocs.examples.params
contains two Beans. Add document annotations to them
@RequestParam
to the QuickStartRequestBean
as the parameter Bean:public class QuickStartRequestBean {
@RequestParam(value = "You name", required = true, description = "please enter your full name", example = "Zhang San")
private String name;
@RequestParam(value = "You age", defaultValue = "18")
private int age;
@RequestParam("Are you a main?")
private boolean man;
// getter/setter...
}
@ResponseProperty
to QuickStartRespBean
as the response Bean:p ublic class QuickStartRespBean {
@ResponseProperty(value = "Response code", example = "500")
private int code;
@ResponseProperty("Response message")
private String msg;
// getter/setter...
}
As only part of the interfaces are selected for the demo, the docs annotations related to these interfaces have been added.
examples-provider:
Introduce Maven:
<dependency>
<groupId>org.apache.dubbo</groupId>
<artifactId>dubbo-api-docs-core</artifactId>
<version>2.7.8</version>
</dependency>
Let's select an interface for the demo:
The quickStart
method in org.apache.dubbo.apidocs.examples.api.impl.QuickStartDemoImpl
QuickStartDemoImpl
implements the org.apache.dubbo.apidocs.examples.api.IQuickStartDemo
interface in the API package.
QuickStartDemoImpl
:@ DubboService
@ApiModule(value = "quick start demo", apiInterface = IQuickStartDemo.class, version = "v0.1")
public class QuickStartDemoImpl implements IQuickStartDemo {
@ApiDoc(value = "quick start demo", version = "v0.1", description = "this api is a quick start demo", responseClassDescription="A quick start response bean")
@Override
public QuickStartRespBean quickStart(@RequestParam(value = "strParam", required = true) String strParam, QuickStartRequestBean beanParam) {
return new QuickStartRespBean(200, "hello " + beanParam.getName() + ", " + beanParam.toString());
}
}
All related document annotations have been added here. Now, enable Dubbo-Api-Docs and create a configuration class at any place as long as it can be scanned by Spring Boot
Create a new configuration class DubboDocConfig
in the org.apache.dubbo.apidocs.examples.cfg
package:
@Configuration
@Profile("dev") // The configuration class is used together with the profile andis loaded if the type of profile is dev.
@EnableDubboApiDocs // Enable Dubbo-Api-Docs
public class DubboDocConfig {
}
All objects related to Dubbo-Api-Docs have been added.
For more detailed examples, please see dubbo-api-docs-examples. A detailed explanation of annotations is in the following. Let's see the effect picture after adding Dubbo-Api-Docs.
org.apache.dubbo.apidocs.examples.ExampleApplication
in the examples-provider project is started.In the examples-provider
directory:
mvn spring-boot:run
Download the source code of the develop branch to start Dubbo Admin:
git clone -b develop https://github.com/apache/dubbo-admin.git
See the description in the Dubbo Admin to start the service:
1. Modify the registry address in dubbo-admin-server/src/main/resources/application.properties.
2. Compile mvn clean package.
3. Start:
mvn --projects dubbo-admin-server spring-boot:run
or
cd dubbo-admin-distribution/target; java -jar dubbo-admin-0.1.jar
4. Access the browser: http://localhost:8080.
5. Both the default account and password are root.
Dubbo-Api-Docs is split according to functions and respectively stored in two repositories.
dubbo-spi-extensions
This repository stores some non-core function extensions of Dubbo. Dubbo-Api-Docs is a sub-module in this repository. Since the repository is a part of Dubbo 3.0 and Dubbo-Api-Docs is developed based on Dubbo 2.7.x, a 2.7.x branch under the Dubbo-Api-Docs is located and added.
The repository contains document-related annotations, annotation scanning capabilities, and usage examples of Dubbo-Api-Docs:
dubbo-api-docs-annotations
: the annotations generated by the document. The interface classes and interface parameters of Dubbo APIs are packaged in a separate jar file, so the annotations are also packaged in a separate jar file. The annotations are described in detail later in this article.dubbo-api-docs-core
: Parses annotations and generates and caches document information. The preceding interfaces related to Dubbo-Api-Docs are also included in the package.dubbo-api-docs-examples
: Usage examplesThe presentation and testing of documents are in the Dubbo Admin project.
@EnableDubboApiDocs
: The configuration annotation to enable the dubbo-api-docs feature@ApiModule
: The class annotation containing Dubbo interface module information, which marks the purpose of an interface class module.
value
: Module nameapiInterface
: The interface through which the provider is implementedversion
: Module version@ApiDoc
: Method annotation containing Dubbo interface information, which marks the purpose of an interface
value
: Interface namedescription
: The description of the interface. It can use HTML tags.version
: Interface versionresponseClassDescription
: The description of the response data@RequestParam
: The annotations for class properties or method parameters, marking request parameters.
value
: Parameter namerequired
: Indicates whether a parameter is requireddescription
: The description of the parameterexample
: Parameter examplesdefaultValue
: The default value of the parameterallowableValues
: The allowed value. After setting this attribute, a drop-down list of parameters will be generated on the interface.
Note
: A drop-down selection box will be generated after setting this attribute.@ResponseProperty
: Class attribute annotation marking response parameters
value
: Parameter nameexample
: The exampleorg.apache.dubbo.config.annotation.Service#async
or org.apache.dubbo.config.annotation.DubboService#async
.dubbo-api-docs-examples
directory in dubbo-spi-extensions or Dubbo-Api-Docs.examples-api
: A jar package containing the interface classes and parameter Beans of the service providerexamples-provider
: A provider project that uses dubbo-spring-boot-starter. Nacos is used as the registry.examples-provider-sca
: A provider project that uses spring-cloud-starter-dubbo. Nacos is used as the registry.examples-provider
, examples-provider-sca
, or both of them. The examples-provider
uses port 20881, and the examples-provider-sca
uses port 20882. Both projects are Spring Boot projects whose startup classes are in the org.apache.dubbo.apidocs.examples
package.http://localhost:8080
in the browserKubeVela 1.0 Introduces the Future of Programmable Application Platform
How Does Seata-AT Ensure Consistency in Distributed Transactions?
506 posts | 48 followers
FollowAlibaba Cloud MVP - November 8, 2019
roura356a - December 2, 2019
JacksonTian - November 27, 2020
Alibaba Cloud Indonesia - October 25, 2022
Alibaba Cloud Native Community - May 16, 2023
Alibaba Developer - January 20, 2022
506 posts | 48 followers
FollowA low-code development platform to make work easier
Learn MoreHelp enterprises build high-quality, stable mobile apps
Learn MoreMulti-source metrics are aggregated to monitor the status of your business and services in real time.
Learn MoreAlibaba Cloud (in partnership with Whale Cloud) helps telcos build an all-in-one telecommunication and digital lifestyle platform based on DingTalk.
Learn MoreMore Posts by Alibaba Cloud Native Community