API Docs&Test

dubbo api docs

Dubbo api documents, test tools, generate documents according to annotations, and provide test functions

Adding some annotations can generate a swagger like document without turning a non web Dubbo project into a web project

How to use?

1. Dubbo api docs annotation added to method parameters of Dubbo project
   • Dubbo provider project introduces dubbo-api-docs-core
   • If Dubbo’s interface and parameters are a separate jar package project, introduce dubbo-api-docs-annotations
   • Add the annotation @EnableDubboApiDocs to the project startup class (marked with @SpringBootApplication) or configuration class (marked with @Configuration) of the provider project to enable the Dubbo API Docs
     • In order to avoid increasing the resource consumption in the production environment, it is recommended to create a configuration class to enable Dubbo API Docs, and use it with the @Profile(“dev”) annotation
     • Of course, Dubbo API Docs consumed a little CPU resources when the project starting and used a little memory for caching. In the future, it will consider putting the contents of the cache into the metadata center

Current Version: Same as Dubbo version

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

Download dubbo-admin Download

3. Start dubbo-admin

4. Visit: http:// localhost:8080

5. Enter the “API Doc” module

Annotation use

• @EnableDubboApiDocs: 配制注解, 启用 dubbo api docs 功能
• @ApiModule: class annotation, dubbo API module information, used to mark the purpose of an interface class module
  • value: module name
  • apiInterface: Provider implemented interface
  • version: module version
• @ApiDoc: method annotation, dubbo API information, used to mark the purpose of an dubbo API
  • value: API name
  • description: API description(HTML tags available)
  • version: API version
  • responseClassDescription: response class description
• @RequestParam: class property/method Parameter annotation, mark request parameters
  • value: parameter name
  • required: true/false required parameter
  • description: parameter description
  • example: parameter example
  • defaultValue: parameter default value
  • allowableValues: Allowed values. After setting this property, a drop-down list will be generated for the parameter
    • Note: a drop-down selection box will be generated after using this property
    • Parameters of boolean type do not need to be set with this property. A drop-down list of true / false will be generated by default
    • Parameters of enumeration type will automatically generate a drop-down list. If you do not want to open all enumeration values, you can set this property separately.
• @ResponseProperty: Class attribute annotation, mark response parameters
  • value: parameter name
  • example: example

Involving repositorys

• dubbo-spi-extensions \branch: 2.7.x\dubbo-api-docs: Dubbo-Api-Docs related annotation ,annotation parsing
• dubbo-admin: Dubbo-Api-Docs document display, test function

Use note

• Get API list direct connection:

Because Dubbo services with different functions may be registered in the same registration center, but the name of the interface used by Dubbo doc is the same, so the interface of Dubbo doc uses direct connection to obtain the list of different interfaces of different functions. The test can be connected directly or through the registration center

• The response bean (the return type of the interface) supports custom generics, but only one generic placeholder.
• About the use of Map: the key of map can only use the basic data type. If the key of map is not the basic data type, the generated key is not in the standard JSON format, and an exception will occur
• The API’s synchronous / asynchronous is from org.apache.dubbo.config.annotation.Service.async

Screenshot