{"id":19492757,"url":"https://github.com/oatpp/oatpp-swagger","last_synced_at":"2025-05-06T21:30:00.494Z","repository":{"id":34792786,"uuid":"142623136","full_name":"oatpp/oatpp-swagger","owner":"oatpp","description":"OpenApi 3.0.0 docs + Swagger UI for oatpp services","archived":false,"fork":false,"pushed_at":"2024-12-01T11:24:49.000Z","size":10360,"stargazers_count":100,"open_issues_count":39,"forks_count":57,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-04-29T23:28:17.276Z","etag":null,"topics":["c-plus-plus","cpp","effortless","oatpp","openapi3","swagger","swagger-ui"],"latest_commit_sha":null,"homepage":"https://oatpp.io/","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/oatpp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-07-27T20:59:35.000Z","updated_at":"2025-04-16T10:00:07.000Z","dependencies_parsed_at":"2022-08-08T04:00:14.643Z","dependency_job_id":"f0e61751-f463-4b8d-80e1-81ac637e050d","html_url":"https://github.com/oatpp/oatpp-swagger","commit_stats":{"total_commits":126,"total_committers":16,"mean_commits":7.875,"dds":0.2777777777777778,"last_synced_commit":"8cb460b546e84b06939a12897c85a6d863c1c53e"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oatpp%2Foatpp-swagger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oatpp%2Foatpp-swagger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oatpp%2Foatpp-swagger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oatpp%2Foatpp-swagger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oatpp","download_url":"https://codeload.github.com/oatpp/oatpp-swagger/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252312137,"owners_count":21727734,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["c-plus-plus","cpp","effortless","oatpp","openapi3","swagger","swagger-ui"],"created_at":"2024-11-10T21:22:52.491Z","updated_at":"2025-05-06T21:30:00.468Z","avatar_url":"https://github.com/oatpp.png","language":"C++","funding_links":[],"categories":["C++"],"sub_categories":[],"readme":"# oatpp-swagger [![oatpp build status](https://dev.azure.com/lganzzzo/lganzzzo/_apis/build/status/oatpp.oatpp-swagger)](https://dev.azure.com/lganzzzo/lganzzzo/_build?definitionId=2)\nSwagger UI for oatpp services\n\nRead more:\n- [About oatpp](https://oatpp.io/)  \n- [What is Swagger UI](https://swagger.io/tools/swagger-ui/)\n- [Endpoint annotation and API documentation in oatpp](https://oatpp.io/docs/components/api-controller/#endpoint-annotation-and-api-documentation).\n\n## Example\n\nFor full example project see: [Example CRUD-API project with Swagger UI](https://github.com/oatpp/example-crud)\n\n## Brief\n\n- Use ```oatpp::swagger::Controller``` with ```oatpp::web::server::HttpConnectionHandler```\n- Use ```oatpp::swagger::AsyncController``` with ```oatpp::web::server::AsyncHttpConnectionHandler```\n\n- Swagger UI location - ```http://localhost:\u003cPORT\u003e/swagger/ui```\n- OpenApi 3.0.0 specification location - ```http://localhost:\u003cPORT\u003e/api-docs/oas-3.0.0.json```\n\nIf you are using ```oatpp::web::server::api::ApiController``` most parts of your endpoints are documented automatically like:\n\n- Endpoint name\n- Parameters\n- Request Body\n\nYou may add more information to your endpoint like follows:\n\n```c++\nENDPOINT_INFO(createUser) {\n  info-\u003esummary = \"Create new User\";\n  info-\u003eaddConsumes\u003cUserDto\u003e(\"application/json\");\n  info-\u003eaddResponse\u003cUserDto\u003e(Status::CODE_200, \"application/json\");\n  info-\u003eaddResponse(Status::CODE_500);\n}\nENDPOINT(\"POST\", \"demo/api/users\", createUser,\n         BODY_DTO(UserDto, userDto)) {\n  return createDtoResponse(Status::CODE_200, m_database-\u003ecreateUser(userDto));\n}\n```\n\n### How to add Swagger UI to your project\n\n1) Add ```oatpp::swagger::DocumentInfo``` and ```oatpp::swagger::Resources``` components to your AppComponents:\n\n```c++\n/**\n *  General API docs info\n */\nOATPP_CREATE_COMPONENT(std::shared_ptr\u003coatpp::swagger::DocumentInfo\u003e, swaggerDocumentInfo)([] {\n\n  oatpp::swagger::DocumentInfo::Builder builder;\n\n  builder\n  .setTitle(\"User entity service\")\n  .setDescription(\"CRUD API Example project with swagger docs\")\n  .setVersion(\"1.0\")\n  .setContactName(\"Ivan Ovsyanochka\")\n  .setContactUrl(\"https://oatpp.io/\")\n\n  .setLicenseName(\"Apache License, Version 2.0\")\n  .setLicenseUrl(\"http://www.apache.org/licenses/LICENSE-2.0\")\n\n  .addServer(\"http://localhost:8000\", \"server on localhost\");\n\n  // When you are using the AUTHENTICATION() Endpoint-Macro you must add an SecurityScheme object (https://swagger.io/specification/#securitySchemeObject)\n  // For basic-authentication you can use the default Basic-Authorization-Security-Scheme like this\n  // For more complex authentication schemes you can use the oatpp::swagger::DocumentInfo::SecuritySchemeBuilder builder\n  // Don't forget to add info-\u003eaddSecurityRequirement(\"basic_auth\") to your ENDPOINT_INFO() Macro!\n  .addSecurityScheme(\"basic_auth\", oatpp::swagger::DocumentInfo::SecuritySchemeBuilder::DefaultBasicAuthorizationSecurityScheme());\n\n  return builder.build();\n\n}());\n\n\n/**\n *  Swagger-Ui Resources (\u003coatpp-examples\u003e/lib/oatpp-swagger/res)\n */\nOATPP_CREATE_COMPONENT(std::shared_ptr\u003coatpp::swagger::Resources\u003e, swaggerResources)([] {\n  // Make sure to specify correct full path to oatpp-swagger/res folder !!!\n  return oatpp::swagger::Resources::loadResources(\"\u003cYOUR-PATH-TO-REPO\u003e/lib/oatpp-swagger/res\");\n}());\n\n```\n\n2) Create ```oatpp::swagger::Controller``` with list of endpoints you whant to document and add it to router:\n\n```c++\nauto swaggerController = oatpp::swagger::Controller::createShared(\u003clist-of-endpoints-to-document\u003e);\nswaggerController-\u003eaddEndpointsToRouter(router);\n```\n\n3) cmake :  \n\nAdd the following lines to your CMakeLists.txt project file\n```\n\nfind_package(oatpp 1.3.0 REQUIRED)\nif(oatpp_FOUND)\n  message(STATUS \"Found oatpp version: ${oatpp_VERSION_STRING}\")\nelse()\n  message(FATAL_ERROR \"Could not find oatpp\")\nendif()\n\nfind_package(oatpp-swagger  1.3.0 REQUIRED)\nif(oatpp-swagger_FOUND)\n  message(STATUS \"Found oatpp-swagger version: ${oatpp-swagger_VERSION_STRING}\")\nelse()\n  message(FATAL_ERROR \"Could not find oatpp-swagger\")\nendif()\n\ninclude_directories(${oatpp_INCLUDE_DIRS})\ninclude_directories(${oatpp-swagger_INCLUDE_DIRS})\n\nadd_definitions( \n  -DOATPP_SWAGGER_RES_PATH=\"${OATPP_BASE_DIR}/bin/oatpp-swagger/res\"\n)\n\ntarget_link_libraries (project PUBLIC\n   // add_your libraries here\n   PUBLIC oatpp::oatpp\n   PUBLIC oatpp::oatpp-swagger\n)\n```\n\n### Customise Swagger UI Paths\n\nTo customise swagger UI endpoints paths add the following component:\n\n```c++\n  /**\n   *  Swagger Controller Paths\n   */\n  OATPP_CREATE_COMPONENT(std::shared_ptr\u003coatpp::swagger::ControllerPaths\u003e, controllerPaths)([] {\n    auto paths = std::make_shared\u003coatpp::swagger::ControllerPaths\u003e();\n    paths-\u003eapiJson = \"custom/path/for/api.json\";       // default is \"api-docs/oas-3.0.0.json\"\n    paths-\u003eui = \"my/custom/path/swagger-ui\";           // default is \"swagger/ui\"\n    paths-\u003euiResources = \"my/custom/path/{filename}\";  // default is \"swagger/{filename}\"\n    return paths;\n  }());\n```\n\n**NOTE:** `paths-\u003eui` and `paths-\u003euiResources` MUST have the same base path - as shown above.\n\n**Done!**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foatpp%2Foatpp-swagger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foatpp%2Foatpp-swagger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foatpp%2Foatpp-swagger/lists"}