Community

Blog Events Webinars Tutorials Forum
  1. Blog
  2. Events
  3. Webinars
  4. Tutorials
  5. Forum
Create Account
×
Community Blog Similar to Swagger! Dubbo-Api-Docs Is Released

Similar to Swagger! Dubbo-Api-Docs Is Released

This article compares and contrasts the positives and negatives of Swagger, Springfox, and Dubbo.

By Ke Ran (Xieying)

1

Background

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:

  • Some of the tools are based on Springfox, which provides a text area for JSON. This is similar to the Admin testing feature.
  • Some are developed based on the Java version of Swagger called the OpenAPI specification generation tool. These tools can display some simple parameters of basic data types as form items.

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:

  • Provide some simple annotations that describe interface information
  • Parse annotations and cache the results when the provider starts
  • Add several interfaces used by Dubbo-Api-Docs to obtain interface information to the provider
  • On the Dubbo Admin side, call the Dubbo interface gateway using HTTP requests through Dubbo generic call.
  • Implement interface information display and interface call on the Dubbo Admin side.
  • The parameters in the following scenarios are displayed as form items, and the others are displayed as JSON items.
  • The method parameter is of the basic data type.
  • The method parameter is a Bean in which the properties are of the basic data type.
  • There are very few third-party dependencies, most of which are originally used in the project.
  • The profile determines whether parameters need to be loaded or not. Production and testing environments can be distinguished by simply modifying the profile during packaging. Moreover, the profile may have already been used.

Today, with the release of Dubbo-Api-Docs, I am pleased to announce that Dubbo users can also enjoy an experience similar to Swagger.

Introduction

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:

  1. Introduce the jar packages related to Dubbo-Api-Docs into Dubbo projects and add annotations similar to Swagger
  2. Check the interface description in the Dubbo Admin and test the interface

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.

Current Version: 2.7.8.1

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

Quick Start

1. Add Dubbo-Api-Docs Annotations to the Method Parameter 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 to the project.
  • Introduce the dubbo-api-docs-core to the Dubbo provider project
  • Add the annotation @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.

Example of Part of Service Interfaces from Project Dubbo-Api-Docs Examples

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 Bean
  • examples-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

  • Add @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...
}
  • Add @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.

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

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.

2

2. Start the Provider Project

  • This example uses Nacos as the registry. Download and start Nacos
  • In the preceding example, the org.apache.dubbo.apidocs.examples.ExampleApplication in the examples-provider project is started.

In the examples-provider directory:

mvn spring-boot:run

3. Download Dubbo Admin

Dubbo Admin warehouse

Download the source code of the develop branch to start Dubbo Admin:

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

4. Enable Access to Dubbo Admin

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.

5. Enter the Interface Documentation Module

  • Enter the IP address and port number of the host where the provider is located in Dubbo Provider IP and Dubbo Provider Port, respectively. Then, click Load Interface List on the right.
  • After the interface list is loaded, click one of the interfaces. The table of interface information and parameters will be displayed on the right side.
  • Fill in the table and click Test at the bottom
  • The response section shows the response example and response result.

Source Code Repository

Dubbo-Api-Docs is split according to functions and respectively stored in two repositories.

1. dubbo-spi-extensions

Dubbo-spi-extensions repository address

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 examples

2. Dubbo Admin

Dubbo Admin repository address

The presentation and testing of documents are in the Dubbo Admin project.

Explanations of Annotations

  • @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 name
    • apiInterface: The interface through which the provider is implemented
    • version: Module version

  • @ApiDoc: Method annotation containing Dubbo interface information, which marks the purpose of an interface

    • value: Interface name
    • description: The description of the interface. It can use HTML tags.
    • version: Interface version
    • responseClassDescription: The description of the response data

  • @RequestParam: The annotations for class properties or method parameters, marking request parameters.

    • value: Parameter name
    • required: Indicates whether a parameter is required
    • description: The description of the parameter
    • example: Parameter examples
    • defaultValue: The default value of the parameter

    • allowableValues: 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.
      • For Boolean parameters, this attribute does not need to be set. A true/false drop-down list is generated by default.
      • For enumeration parameters, a drop-down list will be generated automatically. If the user does not want to allow all enumeration values, set this attribute separately.

  • @ResponseProperty: Class attribute annotation marking response parameters

    • value: Parameter name
    • example: The example

Usage Notes

  • The response bean (the return type of the interface) supports custom generics, but only one generic placeholder is supported.
  • About the Usage of Map: The key of Map must only be a basic data type. Otherwise, the generated data is not in the standard json format, which may result in an exception.
  • The synchronous or asynchronous calling of interface is based on org.apache.dubbo.config.annotation.Service#async or org.apache.dubbo.config.annotation.DubboService#async.

Explanation of the Example

The sample project is in the 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 provider
  • examples-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.

Example Procedure

  1. This example uses Nacos as the registry. Download and start Nacos
  2. Start the 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.
  3. Start Dubbo Admin and access http://localhost:8080 in the browser
  4. Enter the interface document module in Dubbo Admin.
  5. Enter the IP address and port number of the host where the provider is located to Dubbo Provider IP and Dubbo Provider Port, respectively. Then, click Load Interface List on the right.
  6. The interface list will be loaded on the left side. Click one of the interfaces, and the table of interface information and parameters will be displayed on the right side.
  7. Fill in the table and click Test at the bottom
  8. The response section shows the response example and response result
Open Source Front-end Development Dubbo Nacos RPC framework application service middleware Data Format Swagger Duboo-Api-Docs Springfox
0 0 0
Share on

Read previous post:

KubeVela 1.0 Introduces the Future of Programmable Application Platform

Read next post:

How Does Seata-AT Ensure Consistency in Distributed Transactions?

Alibaba Cloud Native Community

508 posts | 49 followers

You may also like

Comments

Alibaba Cloud Native Community

508 posts | 49 followers

Related Products

More Posts by Alibaba Cloud Native Community

See All