This is a 5 minutes tutorial how-to-use (AKA to build your own C++ performant web-service and integrate it with Swagger-UI. Oat++ oatpp) web framework Pre Requirements For : Git, Mac/Linux build-essentials, CMake. For : Git, CMake, MSVC. Windows Install Oat++ Clone oatpp repo: $ git https://github.com/oatpp/oatpp $ oatpp/ clone cd On Mac/Linux: $ mkdir build && build/ $ cmake .. $ make install cd For more detailed instructions see - installing Oat++ on Unix/Linux . On Windows: $ MD build $ build/ $ cmake .. $ cmake --build . --target INSTALL cd For more detailed instructions see - installing Oat++ on Windows . It is a zero-dependency framework, so NO additional installations are required. Now we are able to build services using Oat++. Build and Run Starter Project Clone “oatpp-starter” $ git --depth=1 https://github.com/oatpp/oatpp-starter my-service $ my-service/ clone cd Build “oatpp-starter” on Mac/Linux $ mkdir build && build/ $ cmake .. $ make cd Build “oatpp-starter” on Windows $ MD build $ build/ $ cmake .. $ cmake --build . cd Run compiled executable: Mac/Linux - $ ./my-project-exe Windows - $ .\src\Debug\my-project-exe.exe Now go to ake sure that you can see the response from server localhost:8000 and m { : , : } "statusCode" 200 "message" "Hello World!" Project Structure - src/ | | | | | | | | | | | | | | | - controller/ - MyController.hpp // Endpoints are declared here - dto/ - DTOs.hpp // DTOs are here - App.cpp // main is here - AppComponent.hpp // Application components configuration - contains declared endpoints and their info together with additional Swagger annotations. MyController class - resides in DTOs.hpp. Describes the Data-Transfer-Object used in the "Hello World" response mentioned above. In oatpp DTOs are used in ObjectMapping and Serialization/Deserialization. MyDto class - this is an applications' entry point. Here Application Components are loaded, Controllers' endpoints are added to the Router, and the server starts. App.cpp file - basically it is a collection of components that will be loaded on application start. Here we configure things like which ConnectionProvider to use, port to listen to, which ObjectMapper to use. AppComponent class Integrate Swagger-UI To integrate Swagger-UI in the project we have to do the following: Clone and install module oatpp-swagger Add to oatpp-swagger CMakeLists.txt Add corresponding code to AppComponent.hpp and App.cpp Install oatpp-swagger $ git https://github.com/oatpp/oatpp-swagger $ oatpp-swagger/ clone cd Linux/Mac: $ mkdir build && build/ $ cmake .. $ make install cd Windows: $ MD build $ build/ $ cmake .. $ cmake --build . --target INSTALL cd Add to oatpp-swagger CMakeLists.txt ... (oatpp . REQUIRED) (oatpp-swagger . REQUIRED) ( -lib PUBLIC oatpp::oatpp PUBLIC oatpp::oatpp-swagger ) ( -DOATPP_SWAGGER_RES_PATH= ) ... ## add libs find_package 1.1 0 find_package 1.1 0 # <-- add this target_link_libraries ${project_name} # <-- add this ## define path to swagger-ui res folder add_definitions "${OATPP_BASE_DIR}/bin/oatpp-swagger/res" # <-- add this AppComponent.hpp Here we add and components which give general information about our API document and specify a path to Swagger-UI resources: oatpp::swagger::DocumentInfo oatpp::swagger::Resources ... ... OATPP_CREATE_COMPONENT( :: <oatpp::swagger::DocumentInfo>, swaggerDocumentInfo )([] { oatpp::swagger::DocumentInfo::Builder builder; builder .setTitle( ) .setDescription( ) .setVersion( ) .setContactName( ) .setContactUrl( ) .setLicenseName( ) .setLicenseUrl( ) .addServer( , ); builder.build(); }()); OATPP_CREATE_COMPONENT( :: <oatpp::swagger::Resources>, swaggerResources )([] { oatpp::swagger::Resources::loadResources( OATPP_SWAGGER_RES_PATH ); }()); }; # include "oatpp-swagger/Model.hpp" # include "oatpp-swagger/Resources.hpp" { class AppComponent /** * General API docs info */ std shared_ptr "My Demo Service with Swagger-UI" "C++/oat++ Web Service with Swagger-UI" "1.0" "Mr. Developer" "https://oatpp.io/" "Apache License, Version 2.0" "http://www.apache.org/licenses/LICENSE-2.0" "http://localhost:8000" "server on localhost" return /** * Swagger-Ui Resources */ std shared_ptr return App.cpp Here we add to Router with the list of endpoints we want to document oatpp::swagger::Controller ... { ... docEndpoints = oatpp::swagger::Controller::Endpoints::createShared(); docEndpoints->pushBackAll(myController->getEndpoints()); swaggerController = oatpp::swagger::Controller::createShared(docEndpoints); swaggerController->addEndpointsToRouter(router); ... } # include "oatpp-swagger/Controller.hpp" void run () auto auto Now if everything is ok, and path is set correctly in the , we should be able to build and run our project and see Swagger-UI at in the browser OATPP_SWAGGER_RES_PATH AppComponent.hpp http://localhost:8000/swagger/ui Additional Info for Endpoint Our endpoint is already present in the document with the proper method and path. Oat++ automatically documents most of the endpoints’ info, such as endpoint name, method, path, parameter names, and parameter types. However, there are things that should be specified explicitly. Annotate endpoint with additional information In the file we add above the root with summary and response information: MyController.hpp ENDPOINT_INFO ENDPOINT ENDPOINT_INFO(root) { info->summary = ; info->addResponse<Object<MyDto>>( Status::CODE_200, ); } ENDPOINT( , , root) { dto = MyDto::createShared(); dto->statusCode = ; dto->message = ; createDtoResponse(Status::CODE_200, dto); } "Root endpoint with 'Hello World!!!' message" "application/json" "GET" "/" auto 200 "Hello World!" return Build, Run, and go to in the browser. Refresh http://localhost:8000/swagger/ui Notice, that summary is added to the endpoint and MyDto schema automatically documented in the Models. Expand endpoint info and check that response is documented correctly Basically that’s it 🎉 Now we have Swagger-UI integrated into our project and we can easily add and document endpoints! Add endpoint Let’s add one more "echo" endpoint and see how it is documented in the swagger. In the file MyController.hpp: ENDPOINT_INFO(echo) { info->summary = ; info->addResponse<Object<MyDto>>( Status::CODE_200, ); } ENDPOINT( , , echo, PATH(Int32, status), BODY_STRING(String, message)) { dto = MyDto::createShared(); dto->statusCode = status; dto->message = message; createDtoResponse(Status::CODE_200, dto); } "Echo endpoint with custom message" "application/json" "POST" "/echo/status/{status}" auto return Build and run… Refresh… Expand echo endpoint info - you can see the "status" and "Request Body" parameters: Put in some values: Execute the request and verify that you have a correct response from the server: That’s it. You may experiment by adding more endpoints, playing with parameters, and DTO-fields to see how it is being documented in Swagger-UI. Useful Links repository - oatpp https://github.com/oatpp/oatpp repository - oatpp-swagger https://github.com/oatpp/oatpp-swagger Complete example project with basic CRUD implementation - https://github.com/oatpp/example-crud Previously published at https://medium.com/oatpp/c-oatpp-web-service-with-swagger-ui-and-auto-documented-endpoints-1d4bb7b82c21
