Merge pull request #370 from oatpp/endpoint_info_multiple_examples

Endpoint: Support multiple example values.

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="<user-id-value>"
 
 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<Object<MyDto>>("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<Object<MyDto>>(Status::CODE_200, "application/json")
+    .addExample("Successful Response_1", MyDto::createShared(... /* params */ ));
+
+  info->addResponse<Object<ErrorDto>>(Status::CODE_404, "application/json")
+    .addExample("Error - Not found", ErrorDto::createShared(404, "Not Found"));
+
+  info->addResponse<Object<ErrorDto>>(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>(UserRole::ADMIN))
+    .addExample("Guest", oatpp::Enum<UserRole>(UserRole::GUEST));
+
+}
+```
+
 ## New Modules
 
 - [oatpp-openssl](https://github.com/oatpp/oatpp-openssl) - TLS adaptor for OpenSSL (Recommended to use).

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<std::pair<oatpp::String, oatpp::Any>> 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<std::pair<oatpp::String, oatpp::Any>> examples;
+
+      ContentHints& addExample(const oatpp::String& title, const oatpp::Any& example) {
+        examples.push_back({title, example});
+        return *this;
+      }
     };
     
   public: