diff --git a/changelog/1.2.5.md b/changelog/1.2.5.md index 69f79af7..66cb8c68 100644 --- a/changelog/1.2.5.md +++ b/changelog/1.2.5.md @@ -11,6 +11,7 @@ Contents: - [Headers Multimap](#headers-multimap) - [Better Router API](#better-router-api) - [ORM Clean Section](#orm-clean-section) +- [Swagger-UI Example Values](#swagger-ui-example-values) - [New Modules](#new-modules) ## Introduce ResponseInterceptor @@ -163,6 +164,53 @@ SELECT name::varchar FROM users WHERE userId="" Note: unlike the `:userId` the `:varchar` char-sequence wasn't interpreted as a template parameter (unlike the `:userId`). +## Swagger-UI Example Values + +Now it's possible to add example-values to `RequestBody`, `Response`, and `Parameters` (Path, Headers, Queries) + +### Add Consumes Examples + +```cpp +ENDPOINT_INFO(myEndpoint) { + + info->addConsumes>("application/json") + .addExample("example_1", MyDto::createShared(... /* params here */ )) + .addExample("example_2", MyDto::createShared(... /* params here */ )) + .addExample("example_3", MyDto::createShared(... /* params here */ )); + +} +``` + +### Add Response Examples + +```cpp +ENDPOINT_INFO(myEndpoint) { + + info->addResponse>(Status::CODE_200, "application/json") + .addExample("Successful Response_1", MyDto::createShared(... /* params */ )); + + info->addResponse>(Status::CODE_404, "application/json") + .addExample("Error - Not found", ErrorDto::createShared(404, "Not Found")); + + info->addResponse>(Status::CODE_500, "application/json") + .addExample("Error - DB Connection", ErrorDto::createShared(500, "Can't connect to DB")) + .addExample("Error - Unknown", ErrorDto::createShared(500, "Unknown Error")); + +} +``` + +### Add Parameter Examples + +```cpp +ENDPOINT_INFO(myEndpoint) { + + info->pathParams["userRole"] + .addExample("Admin", oatpp::Enum(UserRole::ADMIN)) + .addExample("Guest", oatpp::Enum(UserRole::GUEST)); + +} +``` + ## New Modules - [oatpp-openssl](https://github.com/oatpp/oatpp-openssl) - TLS adaptor for OpenSSL (Recommended to use). diff --git a/src/oatpp/web/server/api/Endpoint.hpp b/src/oatpp/web/server/api/Endpoint.hpp index b0d883fa..e4d98b62 100644 --- a/src/oatpp/web/server/api/Endpoint.hpp +++ b/src/oatpp/web/server/api/Endpoint.hpp @@ -67,7 +67,12 @@ public: oatpp::Boolean required = true; oatpp::Boolean deprecated = false; oatpp::Boolean allowEmptyValue; - oatpp::Any example; + std::list> examples; + + Param& addExample(const oatpp::String& title, const oatpp::Any& example) { + examples.push_back({title, example}); + return *this; + } }; @@ -116,7 +121,12 @@ public: oatpp::String contentType; oatpp::data::mapping::type::Type* schema; oatpp::String description; - oatpp::Any example; + std::list> examples; + + ContentHints& addExample(const oatpp::String& title, const oatpp::Any& example) { + examples.push_back({title, example}); + return *this; + } }; public: