apache
[Bug] dubbo-rest-openapiin Dubbo 3.3.5: PageResponseand AccessLogResClass Structures Missing from Generated JSON and @SchemaAnnotations Ineffective
Pre-check
- [x] I am sure that all the content I provide is in English.
Search before asking
- [x] I had searched in the issues and found no similar issues.
Apache Dubbo Component
Java SDK (apache/dubbo)
Dubbo Version
dubbo 3.3.5 jdk21
Steps to reproduce this issue
When using Dubbo version 3.3.5 with the dubbo-rest-openapimodule, the generated OpenAPI JSON documentation does not include the schema definitions for the PageResponseand AccessLogResclasses used in the response type ApiResponse<PageResponse<AccessLogRes>>. Additionally, the io.swagger.v3.oas.annotations.media.Schemaannotations appear to have no effect on the generated documentation. This issue hinders the proper generation of API documentation and may affect service consumers who rely on accurate OpenAPI specs.
What you expected to happen
Based on your description, I'll help you create an issue template for Dubbo regarding the problem where PageResponseand AccessLogResclass structures are missing from the generated JSON, and @Schemaannotations aren't working with dubbo-rest-openapiin version 3.3.5. You can directly use or adapt this template when submitting the issue to the Dubbo GitHub repository. Title: dubbo-rest-openapiin Dubbo 3.3.5: PageResponseand AccessLogResClass Structures Missing from Generated JSON and @SchemaAnnotations Ineffective Problem Description: When using Dubbo version 3.3.5 with the dubbo-rest-openapimodule, the generated OpenAPI JSON documentation does not include the schema definitions for the PageResponseand AccessLogResclasses used in the response type ApiResponse<PageResponse<AccessLogRes>>. Additionally, the io.swagger.v3.oas.annotations.media.Schemaannotations appear to have no effect on the generated documentation. This issue hinders the proper generation of API documentation and may affect service consumers who rely on accurate OpenAPI specs. Expected Behavior: The generated OpenAPI JSON should correctly include the schema structures for all classes involved in the API response, including PageResponseand AccessLogRes. The @Schemaannotations should be properly processed and reflected in the generated OpenAPI documentation. Actual Behavior: The schemas for PageResponseand AccessLogResare missing from the generated OpenAPI JSON. Any @Schemaannotations applied to the models or operations are ignored. Steps to Reproduce: Define a Dubbo service operation that returns ApiResponse<PageResponse<AccessLogRes>>. Annotate the relevant classes (e.g., PageResponse, AccessLogRes) or fields with io.swagger.v3.oas.annotations.media.Schema. Configure the application to use dubbo-rest-openapifor generating the OpenAPI documentation (typically accessible via a path like /openapior /v3/api-docs). Start the application and retrieve the generated OpenAPI JSON. Observe that the components.schemassection lacks definitions for PageResponseand AccessLogRes, and any applied @Schemaannotations do not affect the output.
Anything else
No response
Are you willing to submit a pull request to fix on your own?
- [x] Yes I am willing to submit a pull request on my own!
Code of Conduct
- [x] I agree to follow this project's Code of Conduct
API design is crucial for developer experience! Let's build an excellent API. 🌐
🔌 Modern API Design & Best Practices
API Design Principles:
RESTful Design:
- ✅ Resource-based URLs (/users, /posts)
- ✅ HTTP methods (GET, POST, PUT, DELETE, PATCH)
- ✅ Proper status codes (200, 201, 400, 404, 500)
- ✅ HATEOAS where appropriate
- ✅ Versioning strategy (/v1/, /v2/)
GraphQL Design:
- ✅ Well-structured schema
- ✅ Efficient resolvers
- ✅ N+1 query prevention (DataLoader)
- ✅ Pagination (cursor-based)
- ✅ Error handling
API Best Practices:
Request/Response Design:
- Consistent naming conventions (camelCase or snake_case)
- Clear, descriptive error messages
- Pagination for lists
- Filtering, sorting, searching
- Field selection/sparse fieldsets
Documentation:
- OpenAPI/Swagger specification
- Interactive API docs (Swagger UI, Redoc)
- Code examples in multiple languages
- Postman collections
- SDK generation
Security:
- Authentication (JWT, OAuth 2.0, API keys)
- Authorization (RBAC, scopes)
- Rate limiting
- Input validation
- CORS configuration
Performance:
- Response caching (ETag, Cache-Control)
- Compression (gzip, brotli)
- CDN for static responses
- Response time SLAs
My API Development Stack:
Frameworks:
- Node.js: Express, Fastify, NestJS
- Python: FastAPI, Django REST, Flask
- Go: Gin, Echo, Chi
- GraphQL: Apollo, GraphQL Yoga
Tools:
- OpenAPI/Swagger codegen
- Postman/Insomnia
- API Gateway (Kong, Tyk)
- API testing (Supertest, pytest)
What I Can Deliver:
- 📋 API Specification: OpenAPI 3.0 definition
- 💻 Implementation: Clean, maintainable code
- 📚 Documentation: Interactive docs, examples
- ✅ Testing: Comprehensive test suite
- 🔒 Security: Auth, validation, rate limiting
- 📊 Monitoring: Metrics, logging, tracing
API Design Checklist:
- [ ] Consistent naming and structure
- [ ] Comprehensive error handling
- [ ] Input validation
- [ ] Authentication & authorization
- [ ] Rate limiting
- [ ] Versioning strategy
- [ ] OpenAPI documentation
- [ ] Test coverage
- [ ] Performance optimization
- [ ] Monitoring and logging
What's the intended use case? I'd love to help design and implement this API! 🎯
