Head picture.png

Autor | Ke Ran (Evil Shadow)
Fuente | Cuenta oficial nativa de Alibaba Cloud

antecedentes

Swagger es un marco front-end estandarizado y completo para generar, describir, invocar y visualizar servicios web RESTful. La especificación Swagger ha evolucionado gradualmente hacia la especificación OpenAPI.

Springfox es un marco de generación de archivos de descripción de Swagger que integra Swagger y se basa en Sring MVC / Spring Webflux. Genera automáticamente archivos de descripción de Swagger utilizando algunas anotaciones que describen la interfaz definida por él, para que Swagger pueda mostrar y llamar a la interfaz.

Creo que mucha gente ha oído hablar y ha utilizado Swagger y Springfox, así que no los repetiré aquí.

Dubbo-Admin tiene una función de prueba de interfaz, pero carece de documentos de descripción de interfaz, por lo que esta función de prueba es más adecuada para que los desarrolladores de interfaces prueben interfaces. Si otras personas desean usar esta función, primero deben comprender la información de la interfaz a través de la documentación u otros métodos escritos por el desarrollador de la interfaz antes de usar la función para probar la interfaz.

¿Existe alguna función de prueba y visualización de documentos de colección en Dubbo, que pueda proporcionar la interfaz directamente a la persona que llama sin escribir documentos, similar a las herramientas Swagger / Springfox?

Investigué un poco antes y encontré algunas herramientas similares:

Algunos se basan en Springfox y colocan JSON directamente en un campo de texto, que es similar a la función de prueba actual en Admin.
Algunos se basan directamente en la versión Java de Swagger de la herramienta de generación de especificación OpenApI, que puede mostrar parámetros simples de algunos tipos de datos básicos como elementos de formulario.

Todos tienen una cosa en común: convertirán a su proveedor en un proyecto web. Por supuesto, algunos proveedores se inician cargando el contenedor web, y algunos incluso con el proyecto web, por lo que no importa.

Pero también hay proveedores que no son web. ¿Tengo que convertirlo en un proyecto web para la documentación? (¿También necesito introducir un montón de dependencias del marco web? ¿Como Spring MVC?) O al empaquetar el entorno de producción, borre sus referencias y códigos ¿Hay alguna forma más simple?

No existe una especificación RPC en OpenAPI. Swagger es una implementación de OpenAPI, por lo que no se admiten llamadas relacionadas con RPC. Springfox es una herramienta de API RESTful implementada a través de Swagger, y RESTful está basado en la web y Dubbo no se puede usar directamente. Finalmente decidimos implementarlo nosotros mismos:

Proporcione algunas notas sencillas que describan la información de la interfaz.
La anotación se analiza cuando se inicia el proveedor y el resultado de la resolución se almacena en caché.
Agregue varias interfaces para obtener información de la interfaz utilizada por Dubbo-Api-Docs para el proveedor.
En el lado de Dubbo Admin, use la generalización de Dubbo para llamar a la puerta de enlace de la interfaz Dubbo en modo Http.
Realice la visualización de la información de la interfaz y las funciones de la interfaz de llamadas en el lado del administrador de Dubbo.
Los parámetros en los siguientes casos se muestran directamente como elementos de formulario y los demás se muestran como JSON.
- Los parámetros del método son del tipo de datos básicos
- El parámetro del método es un Bean, y los atributos en Bena son los tipos de datos básicos
Pocas dependencias de terceros, incluso la mayoría de ellas se utilizan en su propio proyecto.
Puede decidir si cargar o no a través del perfil. Simplemente modifique el perfil durante el empaque para distinguir entre producción y prueba. Incluso el perfil ya está en uso.

Hoy, estoy muy feliz de anunciar: los usuarios de Dubbo también pueden disfrutar de una experiencia similar a Swagger: se lanza Dubbo-Api-Docs.

Introducción

Dubbo-Api-Docs es una herramienta para mostrar documentos de interfaz dubbo y probar interfaces.

El uso de Dubbo-Api-Docs se divide en dos pasos principales:

Introduzca paquetes jar relacionados con Dubbo-Api-Docs en el proyecto dubbo y agregue anotaciones similares a Swagger.
Vea la descripción de la interfaz y pruebe en Dubbo-Admin.

A través de los dos pasos anteriores, puede disfrutar de una experiencia similar a Swagger y puede desactivar el escaneo de Dubbo-Api-Docs en el entorno de producción.

Dubbo-Api-Docs obtiene actualmente la lista de interfaces de servicio conectándose directamente al nodo de servicio. Al probar la interfaz, puede conectarse directamente oa través del centro de registro. En el futuro, se agregará la forma de obtener la lista de servicios a través del centro de registro, y se agregará nuevo soporte de funciones de acuerdo con el plan de actualización de Dubbo, y se agregarán funciones de acuerdo con las necesidades de la comunidad.

Una vez que se inicia el proveedor de servicios, Dubbo-Api-Docs escaneará las anotaciones relacionadas con los documentos y almacenará en caché los resultados del procesamiento, y agregará algunas interfaces de proveedor Dubbo relacionadas con Dubbo-Api-Docs. Los datos almacenados en caché se pueden colocar en el Centro de metadatos de Dubbo en el futuro.

Versión actual: 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>

Inicio rápido

1. Las anotaciones de Dubbo-Api-Docs se agregan a los parámetros del método del proyecto del proveedor de dubbo.

Si la interfaz y los parámetros del método del proveedor de dubbo están en un proyecto jar separado, introduzca en ese proyecto: dubbo-api-docs-annotations.
El proyecto del proveedor de dubbo presenta dubbo-api-docs-core.
Agregue la anotación @EnableDubboApiDocs a la clase de inicio del proyecto (clase marcada con @SpringBootApplication) o clase de configuración (clase marcada con @Configuration) del proyecto del proveedor para habilitar la función Dubbo Api Docs.

Para evitar aumentar la ocupación de recursos en el entorno de producción, se recomienda crear una clase de configuración separada para habilitar Dubbo-Api-Docs y usarla con la anotación @Profile ("dev"). >
Por supuesto, Dubbo-Api-Docs solo consume un poco más de recursos de CPU cuando se inicia el proyecto y usa un poco de memoria para el almacenamiento en caché.En el futuro, considerará poner el contenido de la caché en el centro de metadatos.

Tome algunas interfaces de servicio en el proyecto dubbo-api-docs-examples como ejemplo :

git clone -b 2.7.x https://github.com/apache/dubbo-spi-extensions.git

Ingrese al directorio dubbo-spi-extensions / dubbo-api-docs / dubbo-api-docs-examples.

Hay dos submódulos en dubbo-api-docs-examples:

examples-api: Un proyecto de paquete jar, que contiene la interfaz de servicio y el parámetro de interfaz Bean.
ejemplos-proveedor: el servidor del proveedor, incluida la implementación del servicio y el iniciador de arranque de primavera.

A continuación, agregamos Dubbo-Api-Docs a estos dos submódulos:

ejemplos-api:

Maven presentó:

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

Hay dos beans en org.apache.dubbo.apidocs.examples.params, agreguemos anotaciones de documentos.

QuickStartRequestBean como bean de parámetro, agregue @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 como bean de respuesta, agregue @ResponseProperty.

public class QuickStartRespBean {

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

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

  // getter/setter略...
}

Dado que solo seleccionamos algunas interfaces como demostraciones, se han agregado las anotaciones de documentos relacionadas con estas interfaces.

ejemplos-proveedor:

Maven presentó:

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

Elegimos una interfaz como demostración:

El método quickStart en org.apache.dubbo.apidocs.examples.api.impl.QuickStartDemoImpl.

QuickStartDemoImpl implementa la interfaz org.apache.dubbo.apidocs.examples.api.IQuickStartDemo en el paquete api.

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

En este punto, se han agregado los comentarios relacionados con los documentos, comencemos Dubbo-Api-Docs. Agregue una nueva clase de configuración, la ubicación es arbitraria, siempre que pueda ser escaneada por Spring Boot.

Agregamos una clase de configuración DubboDocConfig en el paquete org.apache.dubbo.apidocs.examples.cfg:

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

Hasta ahora, se han agregado cosas relacionadas con Dubbo-Api-Docs.

Hay ejemplos más detallados en dubbo-api-docs-examples , que se explican en detalle a continuación. Echemos un vistazo a la imagen del efecto después de agregar Dubbo-Api-Docs:

2. Inicie el proyecto del proveedor

El ejemplo utiliza nacos como centro de registro, descarga e inicia nacos.
En el ejemplo anterior, iniciamos org.apache.dubbo.apidocs.examples.ExampleApplication en el proyecto examples-provider.

En el directorio de proveedores de ejemplos:

mvn spring-boot:run

3. Descarga dubbo-admin

almacén dubbo-admin

dubbo-admin necesita descargar el código fuente de la rama de desarrollo para comenzar.

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

4. Inicie el acceso a dubbo-admin

Consulte las instrucciones en dubbo-admin para comenzar:

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. Introduzca el módulo "Documento de interfaz".

Ingrese la IP y el puerto de la máquina del proveedor en "IP del proveedor de dubbo" y "puerto del proveedor de dubbo", y haga clic en el botón "Cargar lista de interfaces" a la derecha.
Cargue la lista de interfaces en la lista de interfaces de la izquierda, haga clic en cualquier interfaz y la información de la interfaz y el formulario de parámetros se mostrarán a la derecha.
Después de completar el contenido del formulario, haga clic en el botón de prueba en la parte inferior.
La parte de respuesta muestra el ejemplo de respuesta y el resultado de la respuesta real.

Repositorio de código fuente

Dubbo-Api-Docs se divide según funciones y se divide en dos almacenes:

1. extensiones dubbo-spi

dubbo-spi-extensions dirección del almacén

El almacén almacena algunas extensiones de funciones no básicas de dubbo. Dubbo-Api-Docs es un submódulo del almacén. Debido a que el almacén es parte del plan en Dubbo 3.0, Dubbo-Api-Docs se desarrolla en base a Dubbo 2.7.x Sí , entonces la rama 2.7.x se agrega al repositorio y Dubbo-Api-Docs está debajo de esta rama.

El almacén contiene comentarios relacionados con la documentación de Dubbo-Api-Docs, capacidades de escaneo de comentarios y ejemplos de uso:

dubbo-api-docs-annotations: anotaciones relacionadas generadas por la documentación. Teniendo en cuenta que las clases de interfaz y los parámetros de interfaz de dubbo api se planificarán como un paquete jar separado en situaciones reales, las anotaciones también son independientes como un paquete jar. Las notas se explicarán en detalle más adelante en este artículo.
dubbo-api-docs-core: Responsable de analizar anotaciones, generar información de documentos y almacenar en caché. Las interfaces relacionadas con Dubbo-Api-Docs mencionadas anteriormente también están en este paquete.
dubbo-api-docs-examples: ejemplos de uso.

2. Dubbo-Admin

Dirección del almacén Dubbo-Admin

La visualización y la prueba del documento se colocan en el proyecto de administración de dubbo.

Anotación

@EnableDubboApiDocs: configure las anotaciones y habilite la función dubbo api docs.
@ApiModule: anotación de clase, información del módulo de interfaz dubbo, que se utiliza para marcar el propósito de un módulo de interfaz.
- valor: nombre del módulo
- apiInterface: la interfaz implementada por el proveedor
- versión: versión del módulo
@ApiDoc: anotación de método, información de la interfaz dubbo, que se utiliza para marcar el propósito de una interfaz.
- valor: nombre de la interfaz
- descripción: descripción de la interfaz (se pueden utilizar etiquetas html)
- versión: versión de la interfaz
- responseClassDescription: descripción de los datos de respuesta
@RequestParam: Anotación de parámetro de método / atributo de clase, marcando parámetros de solicitud.
- valor: nombre del parámetro
- obligatorio: si se deben pasar parámetros
- descripción: descripción del parámetro
- ejemplo: ejemplo de parámetro
- defaultValue: valor predeterminado del parámetro
- allowableValues: valores permitidos, después de establecer este atributo, se generará una lista desplegable de parámetros en la interfaz
  - Nota: Después de usar este atributo, se generará un cuadro de selección desplegable
  - Los parámetros de tipo booleano no necesitan establecer esta propiedad, y se generará una lista desplegable de verdadero / falso de forma predeterminada
  - Los parámetros del tipo de enumeración generarán automáticamente una lista desplegable. Si no desea abrir todos los valores de enumeración, puede establecer esta propiedad por separado
@ResponseProperty: Anotación de propiedades de clase, anotando parámetros de respuesta.
- valor: nombre del parámetro
- ejemplo: ejemplo

Preste atención

El bean de respuesta (el tipo de retorno de la interfaz) admite genéricos personalizados, pero solo admite un marcador de posición genérico.
Con respecto al uso de Map: Las claves de mapa solo pueden usar tipos de datos básicos. Si la clave del mapa no es el tipo de datos básico, el generado no está en el formato json estándar y se producirá una excepción.
La interfaz síncrona / asíncrona se toma de org.apache.dubbo.config.annotation.Service # async / org.apache.dubbo.config.annotation.DubboService # async.

Descripción de ejemplo

Los proyectos de ejemplo se encuentran en el directorio dubbo-api-docs-examples en dubbo-spi-extensions / Dubbo-Api-Docs :

examples-api: proyecto de paquete jar, incluidas las clases de interfaz y los beans de parámetro del proveedor de servicios.
ejemplos-proveedor: use el proyecto de proveedor de dubbo-spring-boot-starter, el registro usa nacos.
examples-provider-sca: use el proyecto de proveedor de spring-cloud-starter-dubbo, y el registro usa nacos.

Pasos de ejemplo

El ejemplo utiliza nacos como centro de registro, descarga e inicia nacos.
Inicie cualquiera de examples-provider y examples-provider-sca, por supuesto, también puede iniciar ambos. Example-provider usa el puerto 20881 y examples-provider-sca usa el puerto 20882. Ambos proyectos son proyectos de arranque de primavera y la clase de inicio se encuentra en el paquete org.apache.dubbo.apidocs.examples.
Inicie Dubbo-Admin , acceso al navegador:http: // localhost: 8080。
Ingrese al módulo "documento de interfaz" en dubbo-admin.
Ingrese la IP y el puerto de la máquina del proveedor en "IP del proveedor de dubbo" y "puerto del proveedor de dubbo", y haga clic en el botón "Cargar lista de interfaces" a la derecha.
Cargue la lista de interfaces en la lista de interfaces de la izquierda, haga clic en cualquier interfaz y la información de la interfaz y el formulario de parámetros se mostrarán a la derecha.
Después de completar el contenido del formulario, haga clic en el botón de prueba en la parte inferior.
La parte de respuesta muestra el ejemplo de respuesta y el resultado de la respuesta real.

¡Swagger for Dubbo está aquí! Lanzamiento de Dubbo-Api-Docs