Default values for fields in Swagger

[natanael]

Hi there,

Thanks for creating and maintaining this amazing library!

While improving the swagger documentation for an API we are working on we stumbled across the lack of a default on the generated OAS file (/api-docs/oas-3.0.0.json). We mean a default value for a field, like:

DTO_FIELD_INFO(name) {
  info->description = "user first name"; //<-- Fields description is integrated with Swagger-UI.
}
DTO_FIELD(String, name, "yourName") = "Ivan";

Should put out (as per https://swagger.io/specification/#parameterDefault)

"yourName": {
  "type": "string",
  "description": "user first name",
  "default": "Ivan" // <-- Should have a default
}

Maybe it exists as a undocumented feature in the info, like info->default, I could not find it.

[lganzzzo]

Hello @natanael ,

Thanks for opening the issue!

The default values feature is currently not supported in Oat++.

However, it's pretty easy to add this functionality in the form of:

DTO_FIELD_INFO(name) {
  info->description = "user first name"; //<-- Fields description is integrated with Swagger-UI.
  info->default = "Ivan"; //<-- explicit declaration of default value.
}
DTO_FIELD(String, name, "yourName") = "Ivan"; //<-- unfortunately we can't track default value from this place.

So, I would propose whether to wait while we add this functionality (I'll. schedule it for the next nearest release 1.2.0) or you may contribute and add it by yourself (I'll provide the assistance).

Best Regards, Leonid

[natanael]

Thanks for the quick reply! I would love to contribute, but I'm prevented from doing it during business hours by contract, will try later today. Other than a simple PR is there anything I should keep in mind?

[lganzzzo]

I'll put instructions here later today. Also, you may reach me in the oatpp devs chat on Gitter - https://gitter.im/oatpp-framework/Lobby (user oatpp_io_twitter)

In any case it should be two pretty simple PRs to oatpp and to oatpp-swagger

[lganzzzo]

How To Add New Info Property To DTO_FIELD_INFO:

In oatpp

Add new property to Property::Info - https://github.com/oatpp/oatpp/blob/master/src/oatpp/core/data/mapping/type/Type.hpp#L282

In oatpp-swagger

Document the new property here - https://github.com/oatpp/oatpp-swagger/blob/master/src/oatpp-swagger/oas3/Generator.cpp#L102

You may also need to extend the schema object.

Please let me know if you have any questions.

[natanael]

Thanks so much for pointing me on the right direction! The PRs are: https://github.com/oatpp/oatpp/pull/276 https://github.com/oatpp/oatpp-swagger/pull/24 I named it default_value and implemented it as a string but one ideally would want it to match the field, maybe we can do that in a following issue.