Class generator

boost::taar::openapi::generator — Collects route descriptions at registration time and renders an OpenAPI 3.1 document.

Synopsis

// In header: <boost/taar/openapi/generator.hpp>


class generator {
public:
  // member classes/structs/unions

  // A registration observer recording the route under op. 

  class describer {
  public:

    // public member functions
    describer(generator *, operation);
    template<typename Operand, typename Handler> 
      void operator()(Operand const &, Handler const &) const;
  };

  // public member functions
  explicit generator(info);
  generator(generator const &) = delete;
  generator & operator=(generator const &) = delete;
  generator & add_server(std::string, std::string = {});
  generator & add_security_scheme(std::string, security_scheme);
  generator & set_security(std::vector< std::string >);
  generator & set_inline_schemas(bool = true);
  describer describe(operation = {});
  template<typename Summary> describer describe(Summary &&);
  std::size_t operation_count() const noexcept;
  boost::json::object document() const;
  auto handler();
};

Description

Pass describe as a trailing argument of basic_http::register_request_handler. The generator reads the matcher's metadata (method, path template, required headers and cookies) and, for handler::rest handlers, the argument providers (name, location, JSON type, required, description) and the callable's return type. Matchers that OpenAPI cannot express (negation, !=, || over anything but methods, missing method or path) are rejected at compile time.

taar::openapi::generator openapi {{.title = "Users API", .version = "1.0.0"}};

session.register_request_handler(
    method == http::verb::get && target == "/users/{id}",
    taar::handler::rest(&get_user, taar::handler::path_arg("id", "User id")),
    openapi.describe({.summary = "Fetch a user", .tags = {"users"}}));

session.register_request_handler(
    method == http::verb::get && target == "/openapi.json",
    openapi.handler());

`generator` public member functions

```
explicit generator(info document_info);
```
```
generator(generator const &) = delete;
```

generator & operator=(generator const &) = delete;

generator & add_server(std::string url, std::string description = {});

```
generator & add_security_scheme(std::string name, security_scheme scheme);
```
Register a security scheme under name (components.securitySchemes).
Besides being available to operation::security and set_security, a scheme is inferred for any operation whose route or header_arg/cookie_arg/query_arg reads the scheme's apiKey location and name, or whose Authorization header is read when an http scheme exists; the matching parameter is then not listed separately, as the specification asks.
```
generator & set_security(std::vector< std::string > scheme_names);
```
Document-level security: scheme names accepted by every operation that declares none.
```
generator & set_inline_schemas(bool inline_schemas = true);
```
Keep every schema inline instead of hoisting boost::described types into components.schemas and referring to them with $ref.
```
describer describe(operation op = {});
```
Describe the next registered route. Pass as a trailing argument of register_request_handler.

template<typename Summary> describer describe(Summary && summary);

Describe the next registered route by its summary alone.

std::size_t operation_count() const noexcept;

```
boost::json::object document() const;
```
Render the OpenAPI 3.1 document.
```
auto handler();
```
A handler serving document as application/json.

Class generator

Synopsis

Description

generator public member functions

`generator` public member functions