Swagger for Dubbo is here! Dubbo-Api-Docs released

Author | Ke Ran (Evil Shadow)
Source | Alibaba Cloud Native Official Account

background

Swagger is a standardized and complete front-end framework for generating, describing, invoking and visualizing RESTful Web services. The Swagger specification has gradually evolved into the OpenAPI specification.

Springfox is a Swagger description file generation framework that integrates Swagger and is based on Sring MVC/Spring Webflux. It automatically generates Swagger description files by using some annotations that describe the interface defined by it, so that Swagger can display and call the interface.

I believe many people have heard of and used Swagger and Springfox, so I won't repeat them here.

Dubbo-Admin has an interface test function, but it lacks interface description documents, so this test function is more suitable for interface developers to test interfaces. If other people want to use this function, they must first understand the interface information through the documentation or other methods written by the interface developer before using the function to test the interface.

Does Dubbo have a collection of document display and testing functions, which can give the interface directly to the caller without writing documents, similar to Swagger/Springfox tools?

 I did some research before and found some similar tools:

• Some are based on Springfox, and directly put JSON in a text field, which is similar to the current test function in Admin.
• Some are directly based on Swagger's Java version of the OpenApI specification generation tool, which can display simple parameters of some basic data types as form items.

They all have one thing in common: they will turn your provider into a Web project. Of course, some providers are started by loading the web container, and some are even with the web project, so it doesn't matter.

But there are also non-web providers. Do I have to turn it into a web project for documentation? (I also need to introduce a bunch of web framework dependencies? Such as Spring MVC?) Or when packaging the production environment, delete its references and codes Is there a simpler way?

There is no RPC specification in OpenAPI. Swagger is an implementation of OpenAPI, so RPC related calls are not supported. Springfox is a RESTful API tool implemented through Swagger, and RESTful is web-based, and Dubbo cannot be used directly. We finally chose to implement it ourselves:

• Provide some simple notes describing the interface information.
• The annotation is parsed when the provider starts and the result of the resolution is cached.
• Add several interfaces for obtaining interface information used by Dubbo-Api-Docs to the provider.
• On the Dubbo Admin side, use Dubbo generalization to call the gateway of Dubbo interface in Http mode.
• Realize interface information display and call interface functions on Dubbo Admin side.
• The parameters in the following cases are directly displayed as form items, and the others are displayed as JSON.
  • Method parameters are of the basic data type
  • The method parameter is a Bean, and the attributes in Bena are the basic data types
• Few third-party dependencies, even most of them are used in your project itself.
• You can decide whether to load or not through the profile. Simply modify the profile during packaging to distinguish between production and testing. Even the profile is already used.

Today, I am very happy to announce: Dubbo users can also enjoy a Swagger-like experience - Dubbo-Api-Docs is released.

Introduction

Dubbo-Api-Docs is a tool for displaying dubbo interface documents and testing interfaces.

Using Dubbo-Api-Docs is divided into two main steps:

1. Introduce Dubbo-Api-Docs related jar packages in the dubbo project, and add annotations similar to Swagger.

2. View the interface description and test in Dubbo-Admin.

Through the above two steps, you can enjoy a Swagger-like experience, and you can turn off the scanning of Dubbo-Api-Docs in the production environment.

Dubbo-Api-Docs currently obtains the service interface list by directly connecting to the service node. When testing the interface, you can connect directly or through the registration center. In the future, the way to obtain the service list through the registration center will be added, and new function support will be added according to Dubbo's upgrade plan, and functions will also be added according to the needs of the community.

After the service provider is started, Dubbo-Api-Docs will scan docs related annotations and cache the processing results, and add some Dubbo-Api-Docs related Dubbo provider interfaces. The cached data may be placed in the Dubbo Metadata Center in the future.

Current version: 2.7.8.1

<dependency>
    <groupId>org.apache.dubbo</groupId>
    <artifactId>dubbo-api-docs-annotations</artifactId>
    <version>${dubbo-version}</version>
</dependency>
<dependency>
    <groupId>org.apache.dubbo</groupId>
    <artifactId>dubbo-api-docs-core</artifactId>
    <version>${dubbo-version}</version>
</dependency>

Quick start

1. Dubbo-Api-Docs annotations are added to the method parameters of the dubbo provider project

• If the interface and method parameters of the dubbo provider are in a separate jar project, introduce dubbo-api-docs-annotations into the project.
• The dubbo provider project introduces dubbo-api-docs-core.
• Add the annotation @EnableDubboApiDocs to the project startup class (class marked with @SpringBootApplication) or configuration class (class marked with @Configuration) of the provider project to enable the Dubbo Api Docs function.

In order to avoid increasing the resource occupation in the production environment, it is recommended to create a separate configuration class to enable Dubbo-Api-Docs and use it with the @Profile("dev") annotation. >
Of course, Dubbo-Api-Docs only consumes a little more CPU resources when the project is started, and uses a little bit of memory for caching. In the future, it will consider putting the contents of the cache in the metadata center.

Take  some service interfaces in the dubbo-api-docs-examples project as an example :

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.

There are two submodules in dubbo-api-docs-examples:

• examples-api: A jar package project, which contains the service interface and interface parameter Bean.
• examples-provider: the provider server, including the implementation of the spring boot starter and service.

Below we add Dubbo-Api-Docs to these two sub-modules:

examples-api:

Maven introduced:

<dependency>
    <groupId>org.apache.dubbo</groupId>
    <artifactId>dubbo-api-docs-annotations</artifactId>
    <version>2.7.8</version>
</dependency>

There are two beans in org.apache.dubbo.apidocs.examples.params, let's add docs annotations to them.

• QuickStartRequestBean as a parameter bean, add @RequestParam.

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略...
}

• QuickStartRespBean as the response bean, add @ResponseProperty.

public class QuickStartRespBean {

  @ResponseProperty(value = "Response code", example = "500")
  private int code;

  @ResponseProperty("Response message")
  private String msg;

  // getter/setter略...
}

Since we only selected some interfaces as demonstrations, the docs annotations related to these interfaces have been added.

examples-provider:

Maven introduced:

<dependency>
    <groupId>org.apache.dubbo</groupId>
    <artifactId>dubbo-api-docs-core</artifactId>
    <version>2.7.8</version>
</dependency>

We pick an interface as a demonstration:

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.

• In 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());
  }
}

At this point, the docs related comments have been added, let's start Dubbo-Api-Docs. Add a new configuration class at any location, as long as it can be scanned by spring boot.

We add a configuration class DubboDocConfig in the org.apache.dubbo.apidocs.examples.cfg package:

@Configuration
@Profile("dev")  // 配合 Profile 一起使用, 在 profile 为 dev 时才会加载该配制类
@EnableDubboApiDocs  // 开启 Dubbo-Api-Docs
public class DubboDocConfig {
}

So far, Dubbo-Api-Docs related stuff has been added.

 There are more detailed examples in dubbo-api-docs-examples , which are explained in detail below. Let's take a look at the effect picture after adding Dubbo-Api-Docs:

2. Start the provider project

• The example uses nacos as the registration center, download and start nacos.
• In the above example, we start org.apache.dubbo.apidocs.examples.ExampleApplication in the examples-provider project.

In the examples-provider directory:

mvn spring-boot:run

3. Download dubbo-admin

dubbo-admin warehouse

dubbo-admin needs to download the develop branch source code to start.

git clone -b develop https://github.com/apache/dubbo-admin.git

4. Start access dubbo-admin

Refer to the instructions in dubbo-admin to start:

1. 在 dubbo-admin-server/src/main/resources/application.properties 中修改注册中心地址
2. 编译 mvn clean package
3. 启动: 
mvn --projects dubbo-admin-server spring-boot:run
或者
cd dubbo-admin-distribution/target; java -jar dubbo-admin-0.1.jar
4. 浏览器访问: http://localhost:8080
5. 默认帐号密码都是: root

5. Enter the "interface document" module

• Enter the IP and port of the provider's machine in "dubbo provider IP" and "dubbo provider port", and click the "load interface list" button on the right.
• Load the interface list in the interface list on the left, click any interface, and the interface information and parameter form will be displayed on the right.
• After filling in the form content, click the test button at the bottom.
• The response part shows the response example and the actual response result.

Source code repository

Dubbo-Api-Docs is split according to functions and divided into two warehouses:

1. dubbo-spi-extensions

dubbo-spi-extensions warehouse address

The warehouse stores some non-core function extensions of dubbo. Dubbo-Api-Docs is a sub-module of the warehouse. Because the warehouse is part of the plan in Dubbo 3.0, Dubbo-Api-Docs is developed based on Dubbo 2.7.x Yes , so the 2.7.x branch is added to the repository , and Dubbo-Api-Docs is under this branch.
 
The warehouse contains Dubbo-Api-Docs documentation related comments, comment scanning capabilities and usage examples:

• dubbo-api-docs-annotations: related annotations generated by the documentation. Considering that the interface classes and interface parameters of dubbo api will be planned as a separate jar package in actual situations, the annotations are also independent as a jar package. The notes will be explained in detail later in this article.
• dubbo-api-docs-core: Responsible for parsing annotations, generating document information and caching. The aforementioned Dubbo-Api-Docs related interfaces are also in this package.
• dubbo-api-docs-examples: usage examples.

2. Dubbo-Admin

Dubbo-Admin warehouse address

The document display and testing are placed in the dubbo admin project.

Annotation

• @EnableDubboApiDocs: Configure annotations and enable dubbo api docs function.

• @ApiModule: Class annotation, dubbo interface module information, used to mark the purpose of an interface module.
  • value: module name
  • apiInterface: the interface implemented by the provider
  • version: module version
• @ApiDoc: Method annotation, dubbo interface information, used to mark the purpose of an interface.
  • value: interface name
  • description: interface description (html tags can be used)
  • version: interface version
  • responseClassDescription: description of the response data
• @RequestParam: Class attribute/method parameter annotation, marking request parameters.
  • value: parameter name
  • required: Whether to pass parameters
  • description: parameter description
  • example: parameter example
  • defaultValue: parameter default value
  • allowableValues: Allowable values, after setting this attribute, a drop-down list of parameters will be generated on the interface
    • Note: After using this attribute, a drop-down selection box will be generated
    • Parameters of boolean type do not need to set this property, and a true/false drop-down list will be generated by default
    • The parameters of the enumeration type will automatically generate a drop-down list, if you do not want to open all the enumeration values, you can set this property separately
• @ResponseProperty: Annotation of class properties, annotating response parameters.
  • value: parameter name
  • example: example

Use attention

• The response bean (the return type of the interface) supports custom generics, but only supports a generic placeholder.
• Regarding the use of Map: Map keys can only use basic data types. If the key of the Map is not the basic data type, the generated is not in the standard json format, and an exception will occur.
• The synchronous/asynchronous interface is taken from org.apache.dubbo.config.annotation.Service#async / org.apache.dubbo.config.annotation.DubboService#async.

Example description

Example projects are in the dubbo-api-docs-examples directory in dubbo-spi-extensions / Dubbo-Api-Docs  :

• examples-api: jar package project, including the interface classes and parameter beans of the service provider.
• examples-provider: use the provider project of dubbo-spring-boot-starter, and the registry uses nacos.
• examples-provider-sca: use the provider project of spring-cloud-starter-dubbo, and the registry uses nacos.

Example steps

1. The example uses nacos as the registration center, download and start nacos.

2. Start any one of examples-provider and examples-provider-sca, of course, you can also start both. Examples-provider uses port 20881 and examples-provider-sca uses port 20882. Both projects are spring boot projects, and the startup class is under the org.apache.dubbo.apidocs.examples package.

3. Start Dubbo-Admin , browser access:http://localhost:8080。

4. Enter the "interface document" module in dubbo-admin.

5. Enter the IP and port of the provider's machine in "dubbo provider IP" and "dubbo provider port", and click the "load interface list" button on the right.

6. Load the interface list in the interface list on the left, click any interface, and the interface information and parameter form will be displayed on the right.

7. After filling in the form content, click the test button at the bottom.

8. The response part shows the response example and the actual response result.