spectra_openapi (spectra v0.7.0)
View SourceSummary
Functions
Adds a complete response specification to an endpoint.
Creates a basic endpoint specification.
Creates an endpoint specification with documentation.
Generates a complete OpenAPI 3.1 specification from a list of endpoints.
Creates a response builder for constructing response specifications.
Adds a response body to a response builder.
Adds a response body with custom content type to a response builder.
Adds a header to a response builder.
Adds a parameter specification to an endpoint.
Adds a request body to an endpoint.
Adds a request body to an endpoint with additional options.
Types
-type endpoint_spec() :: #{method := http_method(), path := binary(), responses := #{http_status_code() => response_spec()}, parameters := [parameter_spec()], request_body => request_body_spec(), doc => endpoint_doc()}.
-type http_method() :: get | put | post | delete | options | head | patch | trace.
-type http_status_code() :: 100..599.
-type openapi_metadata() :: #{title := binary(), version := binary(), summary => binary(), description => binary(), terms_of_service => binary(), contact => openapi_contact(), license => openapi_license(), servers => [openapi_server()]}.
-type parameter_location() :: path | query | header | cookie.
-type parameter_spec() :: #{name := binary(), in := parameter_location(), required := boolean(), schema := spectra:sp_type_or_ref(), module := module(), description => binary(), deprecated => boolean()}.
-type request_body_spec() :: #{schema := spectra:sp_type_or_ref(), module := module(), content_type => binary(), description => binary()}.
-type response_header_input_spec() :: #{description => binary(), required => boolean(), deprecated => boolean(), schema := spectra:sp_type_or_ref()}.
-type response_header_spec() :: #{description => binary(), required => boolean(), deprecated => boolean(), schema := spectra:sp_type_or_ref(), module := module()}.
-type response_spec() :: #{description := binary(), schema => spectra:sp_type_or_ref(), module => module(), status_code => http_status_code(), content_type => binary(), headers => #{binary() => response_header_spec()}}.
Functions
-spec add_response(Endpoint :: endpoint_spec(), Response :: response_spec()) -> endpoint_spec().
Adds a complete response specification to an endpoint.
This function adds a response that was built using the response builder pattern: response/2, response_with_body/3-4, and response_with_header/4.
Example
Response = spectra_openapi:response(200, <<"Success">>),
Response2 = spectra_openapi:response_with_body(Response, Module, Schema),
Response3 = spectra_openapi:response_with_header(Response2, <<"X-Rate-Limit">>, Module, HeaderSpec),
Endpoint = spectra_openapi:add_response(Endpoint1, Response3).Returns
Updated endpoint map with the response added
-spec endpoint(Method :: http_method(), Path :: binary()) -> endpoint_spec().
Creates a basic endpoint specification.
Equivalent to calling endpoint/3 with an empty documentation map.
Returns
Endpoint map with method and path set
-spec endpoint(Method :: http_method(), Path :: binary(), Doc :: endpoint_doc()) -> endpoint_spec().
Creates an endpoint specification with documentation.
This function creates the foundation for an endpoint with the specified HTTP method, path, and documentation. Additional details like responses, request body, and parameters can be added using the with_* functions.
Documentation Fields
The Doc map can contain:
- summary: Short summary of the endpoint (binary)
- description: Detailed description (binary)
- operationId: Unique identifier for the operation (binary)
- tags: List of tags for grouping (list of binaries)
- deprecated: Whether the endpoint is deprecated (boolean)
- externalDocs: External documentation link (map with url and optional description)
Returns
Endpoint map with method, path, and documentation set
-spec endpoints_to_openapi(MetaData :: openapi_metadata(), Endpoints :: [endpoint_spec()]) -> {ok, json:encode_value()} | {error, [spectra:error()]}.
Generates a complete OpenAPI 3.1 specification from a list of endpoints.
This function takes a list of endpoint specifications and generates a complete OpenAPI document with paths, operations, and component schemas.
Returns
{ok, OpenAPISpec} containing the complete OpenAPI 3.1 document, or {error, Errors} if generation fails
-spec endpoints_to_openapi(MetaData :: openapi_metadata(), Endpoints :: [endpoint_spec()], Options :: [spectra:encode_option()]) -> {ok, json:encode_value() | iodata()} | {error, [spectra:error()]}.
-spec response(StatusCode :: http_status_code(), Description :: binary()) -> response_spec().
Creates a response builder for constructing response specifications.
This function creates a response builder that can be incrementally configured with body and headers before being added to an endpoint using add_response/2.
Example
Response = spectra_openapi:response(200, <<"Success">>),
Response2 = spectra_openapi:response_with_body(Response, Module, Schema),
Response3 = spectra_openapi:response_with_header(Response2, <<"X-Rate-Limit">>, Module, HeaderSpec),
Endpoint = spectra_openapi:add_response(Endpoint1, Response3).Returns
Response builder map with status code and description
-spec response_with_body(Response :: response_spec(), Module :: module(), Schema :: spectra:sp_type_or_ref()) -> response_spec().
Adds a response body to a response builder.
This function sets the schema and module for the response body. Use this with response/2 to build up a complete response specification.
Returns
Updated response builder with body schema added
-spec response_with_body(Response :: response_spec(), Module :: module(), Schema :: spectra:sp_type_or_ref(), ContentType :: binary()) -> response_spec().
Adds a response body with custom content type to a response builder.
This function sets the schema, module, and content type for the response body. Use this with response/2 to build up a complete response specification.
Returns
Updated response builder with body schema and content type added
-spec response_with_header(Response :: response_spec(), HeaderName :: binary(), Module :: module(), HeaderSpec :: response_header_input_spec()) -> response_spec().
Adds a header to a response builder.
This function adds a header specification to the response being built. Multiple headers can be added by calling this function multiple times.
Returns
Updated response builder with header added
-spec with_parameter(Endpoint :: endpoint_spec(), Module :: module(), ParameterSpec :: parameter_spec()) -> endpoint_spec().
Adds a parameter specification to an endpoint.
This function adds a parameter (path, query, header, or cookie) to the endpoint. Multiple parameters can be added by calling this function multiple times.
Parameter Specification
The parameter spec should be a map with these keys:
- name: Parameter name (binary, required)
in: Parameter location (path | query | header | cookie, required)
- required: Whether the parameter is required (boolean, required)
- schema: Schema reference or direct type (spectra:sp_type_or_ref(), required)
- description: Optional description of the parameter (binary)
- deprecated: Mark the parameter as deprecated (boolean). Omit or set to true only; setting deprecated => false is redundant since OpenAPI treats absent and false as equivalent.
Returns
Updated endpoint map with the new parameter added
-spec with_request_body(Endpoint :: endpoint_spec(), Module :: module(), Schema :: spectra:sp_type_or_ref()) -> endpoint_spec().
Adds a request body to an endpoint.
This function sets the request body schema for the endpoint. Typically used with POST, PUT, and PATCH endpoints.
Use with_request_body/4 to also set a custom content type or description.
Returns
Updated endpoint map with request body set
-spec with_request_body(Endpoint :: endpoint_spec(), Module :: module(), Schema :: spectra:sp_type_or_ref(), Opts :: #{content_type => binary(), description => binary()}) -> endpoint_spec().
Adds a request body to an endpoint with additional options.
Like with_request_body/3 but accepts an Opts map for optional fields:
- content_type: Content type override (binary, defaults to application/json)
- description: Optional description of the request body (binary)
Returns
Updated endpoint map with request body set