在线接口文档预言方案

本文介绍了如何利用doxygen生成C++接口文档,包括在VSCode中配置、doxygen的配置文件和CMake集成。同时,探讨了apidoc和Swagger用于RESTfulAPI的文档生成,以及部署到Web服务器进行测试的方法,最终可能选择apidoc并扩展WebSocket支持。
摘要由CSDN通过智能技术生成

在线接口文档预言方案

要求:

​ 支持自动生成接口文档

​ 能够支持在线测试(http,websocket)

​ 对代码没有侵入性

一、目前涉及的相关技术收集

sudo apt update #更新数据
sudo apt upgrade #更新软件
sudo apt install openssh-server #下载安装ssh服务的服务器
sudo apt install openssh-client #下载安装ssh服务的客户端

二、落地 doxygen

1、vscode中安装doxygen插件,设置生成doxygen快捷键,

2、网上学习doxygen的注释字节进行接口注释的编写,

3、新建目录来编译doxygen为可执行程序从而每次接口更新执行执行doxygen即可。

  • sudo apt install doxygen
  • sudo apt install graphviz
  • sudo apt install doxy-doc

4、生成文档,

cmake …

make doc

既可以在build下生成html文件夹。

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

Doxyfile.in doxygen 的配置文件格式

PROJECT_NAME           = "@CMAKE_PROJECT_NAME@"
PROJECT_NUMBER         = @MAJOR_VERSION@.@MINJOR_VERSION@.@PATCH_VERSION@.@BUILD_VERSION@

INPUT                  = @doxy_main_page@ \
                         @CMAKE_CURRENT_LIST_DIR@  \
                         @SrcFile@ 
FILE_PATTERNS          = *.hpp
RECURSIVE              = YES
EXTRACT_ALL            = YES
EXTRACT_PRIVATE        = YES
EXTRACT_STATIC         = YES
EXCLUDE_PATTERNS       = */thirdpart/*
USE_MDFILE_AS_MAINPAGE = @doxy_main_page@
INPUT_ENCODING         = UTF-8
OUTPUT_LANGUAGE        = Chinese

CMakeLists.txt

cmake_minimum_required (VERSION 3.10)

message(STATUS "Build documentation open")
#SrcFile  表示需要解析的目录
set(SrcFile ${CMAKE_CURRENT_LIST_DIR}/../src)

include(build_doxygen.cmake)
build_doxygen()

build_doxygen.cmake

macro(build_doxygen)

FIND_PACKAGE(Doxygen)
IF(${DOXYGEN_FOUND})
    SET(doxyfile_in ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in)
    SET(doxyfile ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)

    CONFIGURE_FILE(${doxyfile_in} ${doxyfile} @ONLY)

    ADD_CUSTOM_TARGET(doc
        COMMAND ${DOXYGEN_EXECUTABLE} ${doxyfile}
        WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
        COMMENT "Generating API documentation with Doxygen"
        VERBATIM)

    install(CODE "execute_process(
      COMMAND ${DOXYGEN_EXECUTABLE} ${doxyfile}
      COMMAND_ECHO STDOUT
      WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/build/
    )")

    INSTALL(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html DESTINATION ${CMAKE_INSTALL_PREFIX}/doc)
else()
MESSAGE(WARNING "Doxygen is needed to build the documentation.Run sudo apt-get install doxygen doxygen-doc doxygen-gui graphviz")
ENDIF()

endmacro()

查阅:

cmake使用doxygen生成document_doxygen cmake_六月的雨唯你的博客-CSDN博客

Doxygen 注释语法规范 - schips - 博客园 (cnblogs.com)

三、落地apidoc

apidoc 官网:apidoc/apidoc: RESTful web API Documentation Generator. (github.com)

1、安装nodejs,因为后面apidoc也是通过nodejs安装最好版本对应,不然会出现错
安装14.2版本

https://blog.csdn.net/qq_36553707/article/details/122849920

2、npm下载apidoc

sudo npm install apidoc -g

3、直接修改执行程序 apidoc (find搜索一下即可)中defaultIncludeFilters 属性,添加hpp,并在解析的时候加上-f “.hpp”

4、安装nginx,将apidoc生成的html发布到web上

nginx安装 https://blog.csdn.net/qq_36553707/article/details/122849920
nginx配置服务 https://blog.csdn.net/qqq2018/article/details/106245836

打开/etc/nginx/nginx.conf,在http的大括号最后加入server配置
server {
    listen 8080;
    server_name example.com;  # 替换为你的域名

    location / {
        root /home/speedbot/workcode/apidoc-demo/apidoc;  # 替换为你 HTML 文件所在的目录
        index index.html;
    }
}

5、测试dapr服务的 http 接口如何访问

https://www.cnblogs.com/magicbowie/p/15596792.html
https://v1-5.docs.dapr.io/zh-hans/reference/api/service_invocation_api/

6、进行在线测试(目前因为dapr跨越问题无法测试,websocket 不支持)

7、支持post和get两种方式,

apidoc升级

进入容器/opt/source/apidoc 替换需要修改的文件即可。

四、落地oat++swaggercpp

直接参考:C++ RESTful web service with Swagger-UI and auto-documented endpoints | oatpp (medium.com)

主要需下载1.1.0版本的oat++和oatswagger,否则会出现一些错误或者编译条件的约束。

接入比较复杂。

五、总结

最后可能还是使用apidoc,只是需要修改源码来增加websocket部分的连接通信。

评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值