openapi.h File Reference

OpenAPI 3.1 generation — source annotations and runtime serving. More...

#include <cwist/sys/app/app.h>

Include dependency graph for openapi.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	cwist_openapi_meta_t
	Per-application metadata for the generated OpenAPI document. More...

Macros
#define	CWIST_OPENAPI_GET(app, path, handler)   cwist_app_get((app), (path), (handler))
#define	CWIST_OPENAPI_POST(app, path, handler)   cwist_app_post((app), (path), (handler))
#define	CWIST_OPENAPI_PUT(app, path, handler)   cwist_app_put((app), (path), (handler))
#define	CWIST_OPENAPI_DELETE(app, path, handler)   cwist_app_delete((app), (path), (handler))
#define	CWIST_OPENAPI_PATCH(app, path, handler)   cwist_app_patch((app), (path), (handler))

Functions
void	cwist_app_enable_openapi (cwist_app *app, const char *json_path, const cwist_openapi_meta_t *meta)
	Serve the app's OpenAPI 3.1 document.
void	cwist_openapi_annotate (cwist_app *app, const char *method, const char *path, const char *summary, const char *tags)
	Attach a summary and tags to one operation of the document.

Detailed Description

OpenAPI 3.1 generation — source annotations and runtime serving.

The CWIST_OPENAPI_* macros register a route normally and leave a parseable declaration in C source for off-line tooling (cwist openapi).

cwist_app_enable_openapi() serves an OpenAPI 3.1 document built from the app's live route table on every request: each HTTP route appears with its path (":id" segments become "{id}" path parameters) and method, however it was registered. cwist_openapi_annotate() adds a summary and tags.

Minimal example:

cwist_openapi_meta_t meta = {
    .title   = "My API",
    .version = "1.0.0",
};
cwist_app_enable_openapi(app, "/openapi.json", &meta);
 
CWIST_OPENAPI_GET(app, "/users", list_users);
cwist_openapi_annotate(app, "GET", "/users", "List users", "users");

Definition in file openapi.h.

Macro Definition Documentation

CWIST_OPENAPI_DELETE

#define CWIST_OPENAPI_DELETE	(		app,
			path,
			handler
	)		cwist_app_delete((app), (path), (handler))

Definition at line 35 of file openapi.h.

CWIST_OPENAPI_GET

#define CWIST_OPENAPI_GET	(		app,
			path,
			handler
	)		cwist_app_get((app), (path), (handler))

Definition at line 32 of file openapi.h.

CWIST_OPENAPI_PATCH

#define CWIST_OPENAPI_PATCH	(		app,
			path,
			handler
	)		cwist_app_patch((app), (path), (handler))

Definition at line 36 of file openapi.h.

CWIST_OPENAPI_POST

#define CWIST_OPENAPI_POST	(		app,
			path,
			handler
	)		cwist_app_post((app), (path), (handler))

Definition at line 33 of file openapi.h.

CWIST_OPENAPI_PUT

#define CWIST_OPENAPI_PUT	(		app,
			path,
			handler
	)		cwist_app_put((app), (path), (handler))

Definition at line 34 of file openapi.h.

Function Documentation

cwist_app_enable_openapi()

void cwist_app_enable_openapi	(	cwist_app *	app,
		const char *	json_path,
		const cwist_openapi_meta_t *	meta
	)

Serve the app's OpenAPI 3.1 document.

Registers GET json_path. The document lists every HTTP route of app at request time (the spec route itself and WebSocket routes excepted), so routes added before or after this call are all included. A second call on the same app is ignored.

Parameters

app	Application to serve the document from.
json_path	URL path of the document; NULL means "/openapi.json".
meta	Document metadata; NULL uses the defaults.

Definition at line 210 of file openapi.c.

References cap, cwist_alloc(), cwist_app_get_ex(), cwist_free(), and cwist_strdup().

cwist_openapi_annotate()

void cwist_openapi_annotate	(	cwist_app *	app,
		const char *	method,
		const char *	path,
		const char *	summary,
		const char *	tags
	)

Attach a summary and tags to one operation of the document.

Takes effect only after cwist_app_enable_openapi() on the same app. Annotating the same method and path again replaces the earlier values.

Parameters

app	Application owning the route.
method	HTTP method name, case-insensitive ("GET", "post", ...).
path	Route path exactly as registered (e.g. "/users/:id").
summary	Operation summary, or NULL.
tags	Comma-separated tag list, or NULL.

Definition at line 242 of file openapi.c.

References cap, cwist_alloc(), cwist_free(), CWIST_HTTP_UNKNOWN, and cwist_strdup().