drogonframework
OpenAPI (Swagger)-compliant REST API self-documenting feature (C++ to OAS JSON spec file generator)
Is your feature request related to a problem? Please describe. It feels so frustrating that, of of all C++ based Web Application Frameworks out there, only two seem to provide built-in support for an OpenAPI (Swagger) self-documenting feature:
-
Oat++ https://github.com/oatpp/oatpp-swagger https://oatpp.io/docs/start/high-level-overview/#swagger-ui-annotations https://oatpp.io/docs/components/api-controller/#endpoint-annotation-and-api-documentation https://giters.com/oatpp/example-crud https://medium.com/oatpp/c-oatpp-web-service-with-swagger-ui-and-auto-documented-endpoints-1d4bb7b82c21 https://dzone.com/articles/c-restful-web-service-with-swagger-ui-and-auto-doc Swagger's official list of open-source integrations, listed by programming languages, references
oat++as the only generator for C++: https://swagger.io/tools/open-source/open-source-integrationsA somewhat similar question: https://github.com/drogonframework/drogon/issues/79
-
Pistache https://github.com/pistacheio/pistache http://pistache.io http://pistache.io/docs/rest-description https://github.com/pistacheio/pistache/blob/6b217cc0c4feb230cbe868334e268b360507f882/examples/rest_description.cc#L66 https://github.com/pistacheio/pistache/blob/6b217cc0c4feb230cbe868334e268b360507f882/examples/rest_description.cc#L52
Describe the solution you'd like It would be great if Drogon could offer a built-in OpenAPI / Swagger-compliant self-documenting feature. Besides other two C++ Web Application Frameworks (Oat++ and Pistache) and which I personally dislike, there is a myriad of other Web Application Frameworks for several other programming languages, offering such support:
- Python: FastAPI, drf-yasg, falcon-swagger-ui, falcon-apispec, safrs, django-rest-swagger
- JavaScript / Node.js: swagger-express, apidoc, hapi-swagger, jsdoc + swagger-jsdoc, oas
- Java: Swagger-Core, SpringFox, and many others
- C#: NSwag, Swashbuckle
- Ruby: Source2Swagger
- PHP: SwaggerPHP
- Go: go-swagger
- etc
The feature described herein falls under a "Code-first (then Annotate)" WebAPI documentation mindset. Which is opposite to a "Design-first" mindset.
Describe alternatives you've considered
I'm currently trying Oat++ with its oatpp-swagger module. But I don't like Oat++ as a C++ Web Application Framework, to begin with.
I'm also trying a Doxygen + Sphinx + Breathe pipeline, hoping to somehow be able to add some JavaDoc / Doxygen-style comments and which could be then auto-translated to OpenAPI / Swagger-compliant JSON spec file. Probably via sphinxcontrib-httpdomain plus sphinx-swagger. But the sphinx-swagger seems to be rather old and no longer maintained since July 1st 2017 (last version being 0.4.0).
Additional context See FastAPI ( https://fastapi.tiangolo.com/features/#automatic-docs ) for an intuitive illustration of what the envisioned feature is. See also these Oatpp + Oatpp-swagger tutorials: https://medium.com/oatpp/c-oatpp-web-service-with-swagger-ui-and-auto-documented-endpoints-1d4bb7b82c21 https://dzone.com/articles/c-restful-web-service-with-swagger-ui-and-auto-doc
Thank you.
That's AWESOME - the timing couldn't have been better, and Drogon rocks! Thank you.
Thanks for the feature request. I’m gonna close this issue, as we already have a work in progress PR open covering this exact topic.
@Mis1eader-dev now this would be nice if they implement it.
Yes I agree, personally I don't have hands-on experience with Swagger. I could start working on a PR when I get a good grasp on Swagger.
Is their any way we can upload a static swagger files in drogon. How we do it on nodeJS
This issue was previously closed as a duplicate because similar Swagger/OpenAPI requests were raised in newer issues. However, since this one contains the most comprehensive information, I’ve reopened it and marked the others as duplicates.