OpenAPI

OpenAPI

Header: <cwist/openapi.h>; generator: cwist openapi

CWIST generates an OpenAPI 3.1 document from Doxygen-style annotations in your C source and can serve it with Swagger UI.

Annotating routes

Declare routes with the CWIST_OPENAPI_* macros and put @openapi.* tags in the comment directly above:

#include <cwist/openapi.h>

/** @openapi.summary List users
    @openapi.description Returns all active users.
    @openapi.tags users,public
    @openapi.response 200 application/json User collection. */
CWIST_OPENAPI_GET(app, "/users", list_users);

/** @openapi.summary Get one user
    @openapi.response 200 application/json The user.
    @openapi.response 404 application/json Unknown id. */
CWIST_OPENAPI_GET(app, "/users/:id", get_user);

The macros (CWIST_OPENAPI_GET, _POST, _PUT, _DELETE, _PATCH) expand to the ordinary cwist_app_* calls, so routing is unchanged; they only give the generator an unambiguous declaration to find. :param path segments become required string path parameters ({id} in the document).

Generating the document

cwist openapi src --output openapi.json --title "Users API" --version 1.0.0
# or take output, title and version from the project manifest:
cwist openapi src --project demo.cwpro

See Project CLI.

Serving Swagger UI

cwist_app_enable_swagger(app, "/docs", "openapi.json");

This registers GET /docs, an HTML page that loads Swagger UI 5 from the unpkg CDN, and GET /openapi.json, which serves the file from disk. The file path is stored process-wide, so the last call wins when several apps enable Swagger in one process. Clients need network access to unpkg to render the page.

The OpenAPI and Swagger guide walks through a complete setup.