The author | KeRan source (evil shadow) | alibaba cloud native public number

background

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

Springfox is a Swagger description file generation framework based on Sring MVC/Spring Webflux implementation. It automatically generates Swagger description files by using annotations defined by its description interface. Enables Swagger to display and invoke interfaces.

Many of you have heard and used Swagger and Springfox.

Interface testing is available in Dubo-admin, but there is no documentation to describe the interface, so it is suitable for interface developers to test interfaces. Others who want to use this feature must know the interface information through the documentation written by the interface developer or other means before they can use this feature to test the interface.

Does Dubbo have collection documentation presentation and testing capabilities that can give interfaces directly to callers without writing documentation, like Swagger/Springfox?

I’ve done some research and found some similar tools:

  • Some are based on Springfox, directly a text field to put JSON, and the current Admin test function is much the same.
  • Some are directly based on Swagger’s Java version of the OpenApI specification generator, which presents simple parameters of the underlying data type as form items.

They all have one thing in common: they turn your provider into a Web project. Of course, some providers are launched via Web container loading, and some are even in conjunction with web projects, so it doesn’t matter.

But there are also non-Web providers, do I have to make it a Web project for documentation? (And a bunch of Web framework dependencies? Like Spring MVC?) Or when the production environment is packaged, remove its references and relevant annotations in the code? Is there an easier way?

There is no RPC specification in OpenAPI, Swagger is the implementation of OpenAPI, so rPC-related calls are not supported. Springfox is a tool for RESTful apis implemented by Swagger, and RESTful is web-based, which Dubbo can’t use directly. We ended up implementing it ourselves:

  • Provide some simple annotations that describe the interface information.
  • The annotations are parsed and the results are cached when the provider is started.
  • Add several interfaces to the provider to get interface information used by Dubo-api-docs.
  • On the Dubbo Admin side, the gateway of the Dubbo interface is invoked through the Dubbo generalization call in Http mode.
  • Display and invoke interface information on the Dubbo Admin side.
  • In the following cases, parameters are displayed directly as form items, while others are displayed as JSON.
    • Method parameters of the underlying data type
    • The method parameter is a Bean, and the properties in Bena are of the underlying data type
  • There are few third-party dependencies, and most of them are already used in your project.
  • Profiles can be used to decide whether to load or not, and a simple change to a profile when packaging can distinguish between production and testing, even if you already use a profile.

Today, I’m happy to announce that Dubbo users can now enjoy Swagger — Dubbo-api-Docs is out.

Introduction to the

Dubbo- apI-docs is a tool for displaying Dubbo interface documents and testing interfaces.

Using Dubo-apI-docs is divided into two main steps:

  1. Introduce dubbo – API-docs jar package in dubbo project and add Swagger like annotations.

  2. View the interface description in dubo-admin and test it.

By following these two steps, you can enjoy a Swagger-like experience and turn off the dubo-apI-Docs scan in production.

Dubo-api-docs currently obtains the interface list of the service by directly connecting to the service node. The interface can be directly connected to or through the registry. In the future, a way to obtain the service list from the registry will be added, and new functions will be supported according to the upgrade plan of Dubbo. Functions will also be added according to the needs of the community.

Dubbo-api-docs scans for Docs annotations and caches the results after the service provider is started, and adds some Dubbo provider interfaces related to dubbo-api-docs. 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>
Copy the code

Quick start

1. Add dubbo – apI-docs annotations to method parameters of the Dubbo provider project

  • Annotations if the interface and method parameters of the Dubbo provider are in a separate JAR project, introduce: Dubbo-api-docs – Annotations in that project.
  • Dubbo provider project introduces Dubbo – API-docs -core.
  • Add the @enableDubBoapidocs annotation to the project startup class of the provider project (annotated with @SpringBootApplication) or to the Configuration class (annotated with @Configuration) to enable the DubboApiDocs functionality.

To avoid increasing resource usage in production environments, it is recommended that a separate configuration class be created to enable Dubo-apI-docs and be used with the @profile (“dev”) annotation. Of course, dubo-api-docs only consumes a little bit more CPU at project startup and uses a little bit more memory for the cache, which will be put into the metadata center in the future.

The following todubbo-api-docs-examplesTake some service interfaces in a project as an example:

git clonehttps://github.com/apache/dubbo-spi-extensions.git - b 2.7 xCopy the code

Go to the dubbo-spi-Extensions /dubbo-api-docs/dubbo-api-docs-examples directory.

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

  • Examples-api: A JAR package project that contains the service’s interface and interface parameter beans.
  • Example-provider: the provider server that contains the Spring Boot initiator and the implementation of the service.

Add dubo-api-docs to these submodules:

examples-api:

Maven is introduced:

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

Org. Apache. Dubbo. Apidocs. Examples. There are two beans in the params, let’s add the docs to them.

  • QuickStartRequestBean as the 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 slightly...
}
Copy the code
  • 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 slightly...
}
Copy the code

Since we have selected only a few interfaces for demonstration purposes, the Docs annotations for those interfaces are now added.

examples-provider:

Maven is introduced:

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

Let’s pick an interface as a demonstration:

Org. Apache. Dubbo. Apidocs. Examples. API. Impl. The quickStart QuickStartDemoImpl method.

QuickStartDemoImpl implements the API package of org. Apache. Dubbo. Apidocs. Examples. API. IQuickStartDemo interface.

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

Now that the docs annotations have been added, let’s start dubo-api-docs. Add a configuration class anywhere that can be scanned by Spring Boot.

We in the org. Apache. Dubbo. Apidocs. Examples. The CFG package a new preparation classes DubboDocConfig:

@Configuration
@Profile("dev")  // The Profile class is loaded only when the Profile is dev
@EnableDubboApiDocs  / / open the Dubbo - Api - Docs
public class DubboDocConfig {}Copy the code

The dubo-api-docs stuff has been added here.

More detailed examples are available in Dubo-api-docs-examples, which are annotated in detail below. Let’s take a look at the result of adding Dubo-api-docs:

2. Start the provider project

  • The example uses NACOS as the registry to download and start nacOS.
  • In the example above, we start examples – the provider in the project org. Apache. Dubbo. Apidocs. Examples. ExampleApplication.

In the examples-provider directory:

mvn spring-boot:run
Copy the code

3. Download the dubbo – admin

Dubbo – admin, warehouse

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

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

4. Enable access to dubo-admin

Follow the instructions in dubo-admin to start:

1. In dubbo - admin - server/SRC/main/resources/application. The properties of modified 2 registry address. MVN --projects dubo-admin-server spring-boot:run or CD dubo-admin-distribution /target; Java - jar dubbo - admin - 0.1. Jar 4. Browser: http://localhost:8080 5. The default account password is rootCopy the code

5. Go to the Interface Document module

  • Enter the IP address and port of the provider’s machine in “Dubbo Provider IP” and “Dubbo Provider Port” respectively, and click “Load Interface List” button on the right.
  • Load the outbound interface list from the interface list on the left. Click any interface. The interface information and parameter list are displayed on the right.
  • After filling in the form, click the test button at the bottom.
  • The response section shows the response examples and actual response results.

Source warehouse

Dubo-api-docs is split by function, in two repositories:

1. dubbo-spi-extensions

Dubbo-spi-extensions repository address

Dubbo-api-docs is a sub-module of the repository, which houses some non-core extensions of Dubbo functions. Since the repository is planned as part of Dubbo 3.0, dubbo-APi-Docs is developed based on Dubbo 2.7.x. So a 2.7.x branch was added to the repository, under which Dubo-apI-docs is located. The repository contains document-related annotations for Dubo-API-docs, annotation scanning capabilities and usage examples:

  • Annotations: Annotations generated from a document. Considering that in practice the Dubbo API interface classes and interface parameters are planned as a separate JAR package, annotations are also a separate JAR package. Annotations are explained in detail later in this article.
  • Dubo-api-docs-core: Responsible for parsing annotations, generating document information and caching. The dubo-api-docs interface mentioned earlier is also included in the package.
  • Dubbo-api-docs-examples: examples.

2. Dubbo-Admin

Dubo-admin Warehouse address

Documentation is presented and tested in the Dubbo Admin project.

Note that

  • EnableDubboApiDocs: configure annotations to EnableDubboApiDocs.

  • @apiModule: Class annotation, dubbo interface module information, used to mark the purpose of an interface class module.

    • Value: indicates the module name
    • ApiInterface: The interface implemented by the provider
    • Version: indicates the module version

  • ApiDoc: method annotation, dubbo interface information, used to label the purpose of an interface.

    • Value: indicates the interface name
    • Description: Interface description (HTML tags can be used)
    • Version: indicates the interface version
    • 10. ResponseClassDescription: a description of the data in response

  • RequestParam: Class attribute/method parameter annotation to annotate request parameters.

    • Value: indicates the parameter name
    • Required: Indicates whether the parameter is required
    • Description: Parameter description
    • Example: Parameter example
    • DefaultValue: indicates the defaultValue of a parameter
    • AllowableValues: Allowed values. After setting this attribute, a drop-down list of parameters is generated on the interface
      • Note: Using this property generates a drop-down selection box
      • Boolean arguments do not set this property, and a true/false drop-down list is generated by default
      • The parameters of an enumeration type automatically generate a drop-down list, and you can set this property separately if you do not want to expose all enumeration values

  • ResponseProperty: Class property annotation, annotating the response parameters.

    • Value: indicates the parameter name
    • Example: the sample

Use attention

  • The response bean (the return type of the interface) supports custom generics, but only one generic placeholder.
  • About using a Map: Map keys can only use basic data types. If the Map key is not a basic data type, the generated JSON file is not in standard format and an exception occurs.
  • Interface of the synchronous/asynchronous from org. Apache. Dubbo. Config. The annotation. Service# async/org. Apache. Dubbo. Config. The annotation. DubboService# async.

example

dubbo-spi-extensions / Dubbo-Api-Docs The dubo-api-docs-examples directory in:

  • Examples-api: JAR package project that contains the service provider’s interface classes and parameter beans.
  • Example-provider: provider project using dubo-spring-boot-starter, registry using NACOS.
  • Example-provider-sca: provider project using spring-cloud-starter-dubbo, registry using NACOS.

Example Usage Procedure

  1. The example uses NACOS as the registry to download and start nacOS.

  2. Start either example-provider or example-provider-SCA, or both. Example-provider uses port 20881 Example-provider-sca uses port 20882. Two projects are spring boot project, start classes in the org. Apache. Dubbo. Apidocs. The examples under the package.

  3. Start dubo-admin and visit http://localhost:8080.

  4. Go to the Interface Documentation module in dubo-admin.

  5. Enter the IP address and port of the provider’s machine in “Dubbo Provider IP” and “Dubbo Provider Port” respectively, and click “Load Interface List” button on the right.

  6. Load the outbound interface list from the interface list on the left. Click any interface. The interface information and parameter list are displayed on the right.

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

  8. The response section shows the response examples and actual response results.

If you are interested in building Dubbo Api Docs, you are welcome to join the Dubbo Api Docs team by searching the group number 34403965. You are also welcome to join the Dubbo open Source discussion group by searching group number 21976540.