docs: improve swagger documentation

...so that old documentation is no longer required

Author: Bycob

CMakeLists.txt

@@ -248,6 +248,11 @@ add_custom_target(
     DEPENDS ${CMAKE_BINARY_DIR}/src/caffe.pb.h ${CMAKE_BINARY_DIR}/src/caffe.pb.cc
 )
 
+# read documentation
+file(
+    READ "${CMAKE_SOURCE_DIR}/docs/api_swagger.md"
+    API_DOC
+)
 
 # dependency on Eigen for confusion matrix fast computation
 if (USE_TF)
@@ -1393,6 +1398,10 @@ configure_file (
   "${PROJECT_SOURCE_DIR}/src/dd_config.h.in"
   "${PROJECT_BINARY_DIR}/dd_config.h"
 )
+configure_file (
+  "${PROJECT_SOURCE_DIR}/src/dd_config.cc.in"
+  "${PROJECT_BINARY_DIR}/dd_config.cc"
+)
 
 # status
 message(STATUS "RELEASE:               ${RELEASE}")

README.md

@@ -92,6 +92,7 @@ curl -X GET https://docker.jolibrain.com/v2/deepdetect_cpu/tags/list
 - templates for the most useful neural architectures (e.g. Googlenet, Alexnet, ResNet, convnet, character-based convnet, mlp, logistic regression, SSD, DeepLab, PSPNet, U-Net, CRNN, ShuffleNet, SqueezeNet, MobileNet, RefineDet, VOVNet, ...)
 - support for sparse features and computations on both GPU and CPU
 - built-in similarity indexing and search of predicted features, images, objects and probability distributions
+- auto-generated documentation based on [Swagger](https://swagger.io/)
 
 
 ## Machine Learning functionalities per library

docs/api_swagger.md

@@ -3,6 +3,7 @@
 set_source_files_properties(
   ${CMAKE_BINARY_DIR}/src/caffe.pb.cc
   ${CMAKE_BINARY_DIR}/src/caffe.pb.h
+  ${CMAKE_BINARY_DIR}/dd_config.cc
   PROPERTIES GENERATED TRUE)
 set_source_files_properties(
   ${CMAKE_BINARY_DIR}/src/caffe.pb.cc
@@ -23,7 +24,7 @@ set(ddetect_SOURCES deepdetect.h deepdetect.cc mllibstrategy.h mlmodel.h
     svminputfileconn.h svminputfileconn.cc txtinputfileconn.h
     txtinputfileconn.cc apidata.h apidata.cc chain_actions.h chain_actions.cc
     service_stats.h service_stats.cc chain.h chain.cc resources.cc ext/rmustache/mustache.h ext/rmustache/mustache.cc
-    utils/oatpp.cc dto/ddtypes.cc utils/db.cpp utils/db_lmdb.cpp ${CMAKE_BINARY_DIR}/src/caffe.pb.cc)
+    utils/oatpp.cc dto/ddtypes.cc utils/db.cpp utils/db_lmdb.cpp ${CMAKE_BINARY_DIR}/src/caffe.pb.cc ${CMAKE_BINARY_DIR}/dd_config.cc)
 
 if (USE_JSON_API)
   list(APPEND ddetect_SOURCES jsonapi.h jsonapi.cc)
@@ -32,7 +33,7 @@ if (USE_HTTP_SERVER)
   list(APPEND ddetect_SOURCES httpjsonapi.cc httpjsonapi.h)
 endif()
 if (USE_HTTP_SERVER_OATPP)
-  list(APPEND ddetect_SOURCES oatppjsonapi.cc oatppjsonapi.h http/app_component.hpp http/swagger_component.hpp http/controller.hpp http/error_handler.hpp http/error_handler.cpp http/access_log.cpp)
+  list(APPEND ddetect_SOURCES oatppjsonapi.cc oatppjsonapi.h http/app_component.hpp http/swagger_component.hpp http/controller.hpp http/error_handler.hpp http/error_handler.cpp http/access_log.cpp http/documentation.cc)
 endif()
 if (USE_HTTP_SERVER OR USE_HTTP_SERVER_OATPP)
   list(APPEND ddetect_SOURCES http/flags.h)

src/CMakeLists.txt

@@ -0,0 +1,6 @@
+#include "dd_config.h"
+
+std::string GET_API_DOC() {
+    static std::string API_DOC = R"apidocumentation(@API_DOC@)apidocumentation";
+    return API_DOC;
+}

src/dd_config.cc.in

@@ -1,6 +1,8 @@
 #ifndef DD_CONFIG_H
 #define DD_CONFIG_H
 
+#include <string>
+
 #define BUILD_TYPE "@BUILD_TYPE@"
 #define GIT_VERSION "@GIT_VERSION@"
 #define GIT_BRANCH "@GIT_BRANCH@"
@@ -20,4 +22,7 @@
   "CUDA_VERSION=@CUDA_VERSION_STRING@ CUDNN_VERSION=@CUDNN_VERSION@ "         \
   "CUDA_ARCH=@CUDA_ARCH@ TENSORRT_VERSION=@TENSORRT_VERSION@"
 
+// Swagger documentation
+std::string GET_API_DOC();
+
 #endif

src/dd_config.h.in

@@ -39,6 +39,7 @@
 #include "dto/service_create.hpp"
 #include "dto/stream.hpp"
 #include "dto/resource.hpp"
+#include "documentation.hpp"
 
 #include OATPP_CODEGEN_BEGIN(ApiController)
 
@@ -64,7 +65,8 @@ class DedeController : public oatpp::web::server::api::ApiController
 
   ENDPOINT_INFO(get_info)
   {
-    info->summary = "Retrieve server information";
+    info->summary = "Returns general information about the deepdetect server, "
+                    "including the list of existing services.";
     info->addResponse<Object<dd::DTO::InfoResponse>>(Status::CODE_200,
                                                      "application/json");
   }
@@ -100,7 +102,7 @@ class DedeController : public oatpp::web::server::api::ApiController
 
   ENDPOINT_INFO(get_service)
   {
-    info->summary = "Retrieve a service detail";
+    info->summary = "Returns information on an existing service";
   }
   ENDPOINT("GET", "services/{service-name}", get_service,
            PATH(oatpp::String, service_name, "service-name"),
@@ -138,7 +140,7 @@ class DedeController : public oatpp::web::server::api::ApiController
 
   ENDPOINT_INFO(create_service)
   {
-    info->summary = "Create a service";
+    info->summary = "Create a new machine learning service";
     info->addConsumes<Object<dd::DTO::ServiceCreate>>("application/json");
   }
   ENDPOINT("POST", "services/{service-name}", create_service,
@@ -164,6 +166,13 @@ class DedeController : public oatpp::web::server::api::ApiController
   ENDPOINT_INFO(delete_service)
   {
     info->summary = "Delete a service";
+    info->queryParams.add("clear", String::Class::getType()).description
+        = "`full`, `lib`, `mem`, `dir` or `index`. `full` clears the model "
+          "and service repository, `lib` removes model files only according "
+          "to the behavior specified by the service's ML library, `mem` "
+          "removes the service from memory without affecting the files, `dir` "
+          "removes the whole directory, `index` removes the index when using "
+          "similarity search. default=`mem`";
   }
   ENDPOINT("DELETE", "services/{service-name}", delete_service,
            PATH(oatpp::String, service_name, "service-name"),
@@ -199,7 +208,9 @@ class DedeController : public oatpp::web::server::api::ApiController
 
   ENDPOINT_INFO(post_train)
   {
-    info->summary = "Do a training";
+    info->summary
+        = "Launches a blocking or asynchronous training job from a service.";
+    info->body.description = dd::GET_TRAIN_PARAMETERS();
   }
   ENDPOINT("POST", "train", post_train, BODY_STRING(oatpp::String, train_data))
   {
@@ -219,7 +230,7 @@ class DedeController : public oatpp::web::server::api::ApiController
   }
   ENDPOINT_INFO(delete_train)
   {
-    info->summary = "Delete a training";
+    info->summary = "Stop and delete a training job";
   }
   ENDPOINT("DELETE", "train", delete_train, QUERIES(QueryParams, queryParams))
   {
@@ -230,7 +241,8 @@ class DedeController : public oatpp::web::server::api::ApiController
 
   ENDPOINT_INFO(create_chain)
   {
-    info->summary = "Run a chain";
+    info->summary = "Run a chain call, that allows to call multiple models "
+                    "sequentially";
   }
   ENDPOINT("POST", "chain/{chain-name}", create_chain,
            PATH(oatpp::String, chain_name, "chain-name"),