oatpp-swagger 项目使用教程

oatpp-swagger 项目使用教程

oatpp-swagger OpenApi 3.0.0 docs + Swagger UI for oatpp services 项目地址: https://gitcode.com/gh_mirrors/oa/oatpp-swagger

1. 项目目录结构及介绍

oatpp-swagger 项目是一个为 oatpp 框架提供 Swagger UI 和 OpenApi 文档支持的开源项目。以下是项目的目录结构及其简单介绍：

oatpp-swagger/
├── cmake/                     # CMake 配置文件
├── res/                       # Swagger UI 静态资源文件
├── src/                       # 源代码目录
│   ├── controller/            # 控制器相关文件
│   ├── document_info/         # 文档信息相关文件
│   ├── resources/             # 资源加载相关文件
│   └── utility/               # 工具类文件
├── test/                      # 测试代码目录
├── .gitignore                 # Git 忽略文件
├── CMakeLists.txt             # CMake 项目文件
├── LICENSE                    # 项目许可证文件
└── README.md                  # 项目说明文件

2. 项目的启动文件介绍

项目的启动主要依赖于 CMakeLists.txt 文件，该文件定义了项目的编译过程和依赖。

以下是 CMakeLists.txt 文件的关键部分介绍：

# 寻找 oatpp 库
find_package(oatpp 1.3.0 REQUIRED)

# 寻找 oatpp-swagger 库
find_package(oatpp-swagger 1.3.0 REQUIRED)

# 包含 oatpp 和 oatpp-swagger 的头文件目录
include_directories(${oatpp_INCLUDE_DIRS})
include_directories(${oatpp-swagger_INCLUDE_DIRS})

# 设置 Swagger UI 静态资源路径
add_definitions(-DOATPP_SWAGGER_RES_PATH="${OATPP_BASE_DIR}/bin/oatpp-swagger/res")

# 链接 oatpp 和 oatpp-swagger 库
target_link_libraries (project PUBLIC oatpp::oatpp PUBLIC oatpp::oatpp-swagger)

3. 项目的配置文件介绍

项目的配置主要通过修改 CMakeLists.txt 文件中的定义来实现，以下是配置文件中一些重要的配置项：

• OATPP_SWAGGER_RES_PATH：指定 Swagger UI 静态资源的路径。
• swaggerDocumentInfo：配置 Swagger 文档的基本信息，如标题、描述、版本、联系人等。
• swaggerResources：加载 Swagger UI 静态资源。

若需要自定义 Swagger UI 的访问路径，可以在 CMakeLists.txt 中添加或修改以下组件：

# 自定义 Swagger UI 路径组件
OATPP_CREATE_COMPONENT(std::shared_ptr<oatpp::swagger::ControllerPaths>, controllerPaths)([] {
    auto paths = std::make_shared<oatpp::swagger::ControllerPaths>();
    paths->apiJson = "custom/path/for/api.json";
    paths->ui = "my/custom/path/swagger-ui";
    paths->uiResources = "my/custom/path/{filename}";
    return paths;
});

以上是 oatpp-swagger 项目的简单使用教程，按照上述步骤进行配置和编译，即可在 oatpp 项目中集成 Swagger UI 和 OpenApi 文档功能。

oatpp-swagger OpenApi 3.0.0 docs + Swagger UI for oatpp services 项目地址: https://gitcode.com/gh_mirrors/oa/oatpp-swagger