Skip to content

Add support for annotated tags and externalDocs#105

Open
mvb-catchsystems wants to merge 2 commits intooatpp:masterfrom
mvb-catchsystems:tag_description
Open

Add support for annotated tags and externalDocs#105
mvb-catchsystems wants to merge 2 commits intooatpp:masterfrom
mvb-catchsystems:tag_description

Conversation

@mvb-catchsystems
Copy link

This adds support for the "tags" element of the root document. This allows tags to have a description and an optional URL for external documentation. This is backwards compatible: Tags which are not explicitly declared via a call to addTag are added to the list of tags (but their description will remain empty).

It also adds support for the "externalDocs" element of the root document.

Example usage

/**
 *  General API docs info
 */
OATPP_CREATE_COMPONENT(std::shared_ptr<oatpp::swagger::DocumentInfo>, swaggerDocumentInfo)([] {

  oatpp::swagger::DocumentInfo::Builder builder;

  builder
  .setTitle("User entity service")
  .setDescription("CRUD API Example project with swagger docs")
  .setVersion("1.0")
  .setContactName("Ivan Ovsyanochka")
  .setContactUrl("https://oatpp.io/")

  .setLicenseName("Apache License, Version 2.0")
  .setLicenseUrl("http://www.apache.org/licenses/LICENSE-2.0")
  .setExternalDocs("https://oatpp.io/docs/modules/oatpp-swagger/", "swagger docs")
  .addServer("http://localhost:8000", "server on localhost")

  .addTag("authentication", "Really important information about the login process")
  .addTag("user", "User-related operations")

  .setExternalDocsForTag("authentication", "https://en.wikipedia.org/wiki/Salt_(cryptography)", "background information")

  return builder.build();

}());

Signed-off-by: Martijn van Buul <martijn@catchsystems.nl>
@mvb-catchsystems
Copy link
Author

This would fix #85 (well, it fixes the underlying need of that issue)

Signed-off-by: Martijn van Buul <martijn@catchsystems.nl>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant