[Feature] Dubbo Triple OpenAPI Support Requirements

[oxsean]

Background

There is already a Metadata Service in Dubbo. Why consider introducing support for OpenAPI? There are several considerations:

• Standardization and Ecosystem Support: OpenAPI is an industry standard with broad support and an ecosystem. Many tools and platforms directly support OpenAPI, making it easy to integrate and use these tools for API management and testing, such as Apifox, Postman, APIs.guru, etc. Users can conveniently import and use these tools for API management, testing, and monitoring.
• Readability and Documentation Generation: OpenAPI's description is more intuitive and readable, helping developers quickly understand and use the API. Moreover, OpenAPI tools can automatically generate interactive API documentation, simplifying the work of document writing and maintenance.
• Automation and Testing Support: OpenAPI toolchains support the automatic generation of client code, test cases, etc., which can improve development and testing efficiency. You can use these tools for automated testing and verification to ensure the correctness and stability of the API.
• Interoperability and Scalability: OpenAPI is a standardized description language that can achieve interoperability between different platforms and languages. It also has good scalability to meet future API description needs.
• Community and Industry Trends: OpenAPI is a widely accepted standard, with many companies and developers using it. Joining the OpenAPI ecosystem can keep you consistent with the industry and get support and resources from the community.

Introducing OpenAPI support will greatly enhance the management and efficiency of Dubbo services, helping developers develop, test, and maintain API services more efficiently.

Development Directions

Code First Approach
The Code First approach emphasizes defining the structure and logic of the API by writing code, rather than defining data structures or interface specifications first. In this approach, developers directly write code to implement business logic and convert it into a standard API description format using specific tools or frameworks.

Applicable Scenarios

• Want to define and implement APIs through code.
• Need to integrate with existing code libraries to quickly generate OpenAPI-formatted metadata.
• Want to use automated tools to generate API documentation and client code to improve development efficiency.

Solution

• Provides an intuitive and simple way to define and implement APIs, reducing the workload of manually writing API documentation.
• Can be integrated with existing development tools and processes, improving team development efficiency and collaboration.
• Reduces human errors through automatically generated API documentation.

Schema First Approach
The Schema First approach emphasizes defining the data structure and interface specifications of the API first (usually using JSON or YAML format), and then implementing specific business logic based on these specifications. In this approach, developers can define API specifications to constrain the behavior and data format of the interface, and then generate corresponding code or documentation.

Applicable Scenarios

• Need to generate stub similar to gRPC using existing JSON format OpenAPI.
• Want to utilize existing OpenAPI specifications to generate code, rather than redefining and implementing APIs.

Solution

• Provides a way to generate code based on existing OpenAPI specifications, which can quickly generate server-side and client-side code, reducing redundant work. Additionally, because interfaces are defined based on IDL, cross-language compatibility becomes easier.
• Helps teams quickly prototype and test new APIs. Once the API definition is complete, front-end and back-end development can proceed in parallel through API mocking, speeding up development and deployment.
• By using existing OpenAPI specifications to generate test cases, comprehensive functional and performance testing can be performed, improving test coverage and accuracy.

User Requirements

Export OpenAPI Schema
For existing services, support exporting JSON-format OpenAPI descriptions. Specific requirements include:

• Access to OpenAPI Schema through a REST address.
• Include all services exported from Dubbo, differentiate services using Tags, and assign each method a unique operationId.
• Users should be able to customize the exported OpenAPI Schema through annotations or configuration files, specifying server addresses, supported authentication methods, and supported content types.
• Complete Java type mapping to OpenAPI and support annotations for configuring types and formats.
• Support for advanced OpenAPI features like oneOf, anyOf, allOf for inheritance.
• Swagger Java SDK should be an optional dependency for exporting OpenAPI descriptions. If users add the Swagger Java JAR dependency, they should be able to use Swagger's annotations and implementations for advanced customization.
• If the swagger-web dependency is included, users should be able to access a web address for visualizing and testing APIs (e.g., https://petstore.swagger.io).
• Support uploading the OpenAPI schema to third-party API testing platforms like Apifox via SPI for a complete API integration flow(https://apifox-openapi.apifox.cn/api-173409873).

Import and Generate Stub from OpenAPI Schema

Based on a local or network (configured URL) OpenAPI Schema, generate Java service interfaces and model objects (request, response, enum).
Requirements include:

• Write a maven plugin to read OpenAPI Schema and generate corresponding stub code, similar to gRPC.
• Users should be able to customize code generation naming styles and paths, as well as package-related information through maven plugin configuration.
• Support wildcard configuration of schema paths, able to read multiple schemas and reference types.
• Provide clear output for schema definition errors.
• Support custom template generation.
• Support incremental generation, no modification if there are no changes.
• Generate API testing code (optional).
• Generate service implementation skeleton code (optional).
• Base64 encode the used OpenAPI in the code for embedding, returning it directly when accessing the rest address.

Implementation References
Export OpenAPI Schema

• Consider adding a method specifically for accessing OpenAPI Schema to the existing org.apache.dubbo.metadata.MetadataService. After exporting this method in a restful manner, it can be accessed via a restful address.
• The strong dependency on Swagger can be put into a plugin, and the related functions can be implemented in the plugin, adding a SwaggerService to connect web capabilities.
• In the future, HTTP access will be unified into rest. Therefore, only need to read the rest mapping in RequestMappingRegistry.
• Consider adding an openapi configuration object to configure the required parameters.
• OpenAPI has clear definitions for HTTP error codes and error response objects, which need to be considered in the design.

[elysium-w]

@oxsean I'm deep learning dubbo recently,and I'm willing to contribute this feature.Could you assign this issue to me?

[heliang666s]

I'm very interested in this issue, please assign it to me @oxsean

[oxsean]

@elysium-w Sorry, @heliang666s was working on this feature.