OpenAPI (Swagger)-compliant REST API self-documenting feature (C++ to OAS JSON spec file generator)

[smihaila]

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

  A somewhat similar question: How does this compare to Oat++ ? #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.

[marty1885]

PR #923 is working on the exact feature.

[smihaila]

That's AWESOME - the timing couldn't have been better, and Drogon rocks!
Thank you.

[rbugajewski]

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.

[feliwir]

Why is this closed? #923 was never implemented / finished

[aryankarim]

@Mis1eader-dev now this would be nice if they implement it.

[Mis1eader-dev]

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

[vanarp0915]

Is their any way we can upload a static swagger files in drogon. How we do it on nodeJS