drogonframework / drogonframework/drogon
OpenAPI (Swagger)-compliant REST API self-documenting feature (C++ to OAS JSON spec file generator)
- Dominant language
- C++
- Stars
- 14.3k
- Forks
- 1.4k
- Avg merge
- 1d 13h
- Merged PRs (30d)
- 14
Description
**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: 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.
Contributor guide
Assessment
This issue has not been assessed yet.