{"id":19000698,"url":"https://github.com/flaviomarcio/qapidoc","last_synced_at":"2026-04-13T21:31:45.787Z","repository":{"id":209546541,"uuid":"467020133","full_name":"flaviomarcio/qapidoc","owner":"flaviomarcio","description":"Qt-API Documentation for OpenAPI/Swagger","archived":false,"fork":false,"pushed_at":"2023-11-15T15:35:53.000Z","size":161,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-02-21T13:19:34.983Z","etag":null,"topics":["cpp","openapi","openapi-specification","openapi3","qt","rest-api","swagger","swagger-ui"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/flaviomarcio.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}},"created_at":"2022-03-07T09:09:35.000Z","updated_at":"2023-11-27T22:18:37.000Z","dependencies_parsed_at":"2023-11-28T00:37:20.982Z","dependency_job_id":null,"html_url":"https://github.com/flaviomarcio/qapidoc","commit_stats":null,"previous_names":["flaviomarcio/qapidoc"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/flaviomarcio/qapidoc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flaviomarcio%2Fqapidoc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flaviomarcio%2Fqapidoc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flaviomarcio%2Fqapidoc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flaviomarcio%2Fqapidoc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/flaviomarcio","download_url":"https://codeload.github.com/flaviomarcio/qapidoc/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flaviomarcio%2Fqapidoc/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31771813,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-13T20:17:16.280Z","status":"ssl_error","status_checked_at":"2026-04-13T20:17:08.216Z","response_time":93,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["cpp","openapi","openapi-specification","openapi3","qt","rest-api","swagger","swagger-ui"],"created_at":"2024-11-08T18:08:10.280Z","updated_at":"2026-04-13T21:31:45.766Z","avatar_url":"https://github.com/flaviomarcio.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# QApiDoc 0.1.0\n***QApiDoc*** is a Qt library to generate swagger.json file for Swagger Spec version 2.0. Create a public documentation REST API using Swagger 2.0 for Qt/C++ Language. ***QApiDoc*** only responsibility is to generate the swagger.json file. The swagger.json file is responsible for containing all the documentation for your REST API. This file must be attached to the Swagger UI (User Interface) files. \n\n\n\n## Working architecture\n\u003e## Support\n\u003e Qt5, Qt6\n\n## Prerequisits\n\u003e```bash\n\u003e mkdir myproject;\n\u003e cd myproject;\n\u003e git clone git@github.com:flaviomarcio/qapidoc.git;\n\u003e```\n\u003eCheck example in qapidoc/example/*\n\n\n## CMake Build information\n\n\u003e```\n\u003e## initial CMake parameters \n\u003e\n\u003e-GNinja\n\u003e-DCMAKE_BUILD_TYPE:STRING=Debug\n\u003e-DCMAKE_PROJECT_INCLUDE_BEFORE:PATH=%{IDE:ResourcePath}/package-manager/auto-setup.cmake\n\u003e-DQT_QMAKE_EXECUTABLE:STRING=%{Qt:qmakeExecutable}\n\u003e-DCMAKE_PREFIX_PATH:STRING=%{Qt:QT_INSTALL_PREFIX}\n\u003e-DCMAKE_C_COMPILER:STRING=%{Compiler:Executable:C}\n\u003e-DCMAKE_CXX_COMPILER:STRING=%{Compiler:Executable:Cxx}\n\u003e-DCMAKE_INSTALL_PREFIX=~/build/myproject/install/release\n\u003e```\n\n\u003e```bash\n\u003e cd qapidoc\n\u003e mkdir build;\n\u003e cd build;\n\u003e cmake ..\n\u003e make;\n\u003e make install;\n\u003e```\n\n## QMake Build information\n\n\u003e```bash\n\u003e cd qapidoc\n\u003e qmake qapidoc.pro\n\u003e make;\n\u003e make install;\n\u003e ls -l;\n\u003e```\n\n## Configure QMake project\n\n\u003e```c++\n\u003e#CONFIG+=c++17\n\u003eCONFIG+=console\n\u003eCONFIG+=silent\n\u003eCONFIG -= debug_and_release\n\u003eQT += gui core widgets\n\u003e\n\u003eTEMPLATE = app\n\u003eTARGET = demo\n\u003e\n\u003einclude($$PWD/../../../qapidoc/qapidoc.pri)\n\u003e```\n## Implementation\n\u003eUsing source of example of repository\n\u003e## Documentation for methods and classes\n\u003eBased on class/structs ***Qt*** and ***c++*** , create full documentation to ***OpenAPI***.\n\u003e```c++\n\u003eclass PersonCrud : public QObject\n\u003e{\n\u003e    Q_OBJECT\n\u003epublic:\n\u003e    Q_API_DOC_INFO(){\n\u003e        document-\u003e\n\u003e            host(\"localhost\").\n\u003e            basePath(\"/v1/crud\").\n\u003e            consumes(\"application/json\").\n\u003e            produces(\"application/json\").\n\u003e            schemes(stpsHttp);\n\u003e\n\u003e        document-\u003einfo()\n\u003e            .title(\"Person CRUD V1\")\n\u003e            .version(\"1.0.0\")\n\u003e            .termsOfService(\"http://www.apache.org/licenses/LICENSE-2.0.txt\")\n\u003e            .description(\"Sample API Description\")\n\u003e            ;\n\u003e\n\u003e        document-\u003einfo().contact()\n\u003e            .name(\"Flavio Portela\")\n\u003e            .email(\"fmspxdev@gmail.com\")\n\u003e            .url(\"https://github.com/flaviomarcio/qtreforce-sdk\")\n\u003e            ;\n\u003e\n\u003e        document-\u003einfo().license()\n\u003e            .name(\"Apache License - Version 2.0, January 2004\")\n\u003e            .url(\"http://www.apache.org/licenses/LICENSE-2.0\")\n\u003e            ;\n\u003e    }\n\u003e\n\u003epublic:\n\u003e    explicit PersonCrud(QObject *parent=nullptr);\n\u003e\n\u003e    Q_API_DOC_PATH(search){\n\u003e        path-\u003e\n\u003e            operation(sptoGet)\n\u003e                .operationId({})\n\u003e                .responses(QApiResponse().statusCode(200))\n\u003e                .parameters(QApiParameter().name(\"id\").typeParameter(QMetaType::QUuid))\n\u003e                .parameters(QApiParameter().name(\"name\").required(true).type(QMetaType::QString));;\n\u003e    }\n\u003e    QVariant search();\n\u003e\n\u003e    Q_API_DOC_PATH(person){\n\u003e        path-\u003e\n\u003e            operation(sptoPost)\n\u003e                .operationId({})\n\u003e                .responses(QApiResponse().statusCode(200))\n\u003e                .parameters(QApiParameter().name(\"id\").typeParameter(QMetaType::QUuid))\n\u003e                .parameters(QApiParameter().name(\"name\").required(true).type(QMetaType::QString));\n\u003e\n\u003e        path-\u003e\n\u003e            operation(sptoPut)\n\u003e                .operationId({})\n\u003e                .responses(QApiResponse().statusCode(200))\n\u003e                .parameters(QApiParameter().name(\"id\").typeParameter(QMetaType::QUuid))\n\u003e                .parameters(QApiParameter().name(\"name\").required(true).type(QMetaType::QString));;\n\u003e\n\u003e        path-\u003e\n\u003e            operation(sptoDelete)\n\u003e                .operationId({})\n\u003e                .responses(QApiResponse().statusCode(200))\n\u003e                .parameters(QApiParameter().name(\"id\").typeParameter(QMetaType::QUuid));\n\u003e    }\n\u003e    QVariant person();\n\u003e\n\u003e};\n\u003e```\n\u003e\n\u003eExtracting documentation\n\u003e```c++\n\u003e#include \u003cQCoreApplication\u003e\n\u003e#include \u003cQDebug\u003e\n\u003e#include \u003cQProcess\u003e\n\u003e#include \u003cQJsonDocument\u003e\n\u003e#include \"./example_object.h\"\n\u003e\n\u003eint main(int argc, char *argv[])\n\u003e{\n\u003e    QCoreApplication a(argc, argv);\n\u003e    \n\u003e    //documented class \n\u003e    AnnotationExample::PersonCrud personCrud;\n\u003e\n\u003e    //export to QVariantHash\n\u003e    auto documentation=personCrud.documentation().toHash();\n\u003e\n\u003e    //export to Json\n\u003e    qDebug()\u003c\u003cQJsonDocument::fromVariant(documentation).toJson();\n\u003e\n\u003e    return QProcess::NormalExit;\n\u003e}\n\u003e```\n\n\n\n## Swagger (Open API) - version 2.0\n\nQApiDoc follows the specification 2.0 because it is more popular in the market and also because it is considered a more stable version to exist the longest. QApiDoc does not yet support the Swagger 3.0 version, but depending on the demand and contributions to the project it may evolve to support spec 3.0.\n\nThe main prerequisite for working with QApiDoc is to know the Swagger 2.0 specification that can be viewed in the link below.\n\nhttps://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md\n\nhttps://swagger.io/docs/specification/2-0/basic-structure/\n\n## Json Schema\n\nhttps://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#schemaObject\n\nhttp://json-schema.org\n\n## Swagger References and Tutorials \n\nhttps://swagger.io/swagger/media/blog/wp-content/uploads/2017/02/Documenting-An-Existing-API-with-Swagger-2.pdf\n\nhttps://idratherbewriting.com/learnapidoc/pubapis_swagger_intro.html\n\n\n## Swagger Tools\n\n- Swagger:\nhttps://swagger.io\n\n- Swagger Editor:\nhttps://editor.swagger.io\n\n- Swagger Hub:\nhttps://swagger.io/tools/swaggerhub\n\n- The classic swagger sample:\nhttp://petstore.swagger.io\n\n- Tools and Integrations:\nhttps://swagger.io/tools/open-source/open-source-integrations\n\n\n## Swagger UI distribution files\n\nFor you to produce a page containing a Swagger documentation you need the Swagger UI distribution files.\n\nThese files you can find in the github swagger-api / swagger-ui repository.\n\nhttps://github.com/swagger-api/swagger-ui/tree/master/dist\n\n![image](https://user-images.githubusercontent.com/20048296/39937130-2925f868-5525-11e8-921d-c9ff0f59fefd.png)\n\n\nFirst you need to download the swagger user interface files and generate the swagger.json file. You then need to change the index.html file to indicate the relative path of the location where the swagger.json file is located on your web server that is hosting the swagger user interface files.\n\nSee an example below.\n\n![image](https://user-images.githubusercontent.com/20048296/39946376-49ad0df0-5544-11e8-8a5c-0980f5e6c257.png)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflaviomarcio%2Fqapidoc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fflaviomarcio%2Fqapidoc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflaviomarcio%2Fqapidoc/lists"}