bureaucrat v0.2.7 Bureaucrat.SwaggerSlateMarkdownWriter

This markdown writer integrates swagger information and outputs in a slate-friendly markdown format. It requires that the decoded swagger data be available via Application.get_env(:bureaucrat, :swagger), eg by passing it as an option to the Bureaucrat.start/1 function.

It can also be configured with the following options, set via the :writer_opts argument of Bureaucrat:

  • :plainntext: If false, will not render the plaintext version of request/response examples. Defaults to true

Link to this section Summary

Functions

Find the details of an API operation in swagger by operationId

Pretty-print a JSON response, handling body correctly

Group a list of tagged records, first by tag, then by operation_id.

Tag a single record with swagger tag and operation_id.

Populate each test record with private.swagger_tag and private.operation_id from swagger.

Writes a list of Plug.Conn records to the given file path.

Writes all examples of a given operation (Controller action) to file.

Writes the authentication details to the given file.

Writes a single request/response example to file

Write the list of request/response headers

Writes a single API model schema to the given file.

Writes the fields of the given model to file.

Writes the API request/response model schemas to the given file.

Writes the API details and exampels for operations having the given tag.

Writes the document title and api summary description.

Writes the parameters table for given swagger operation to file.

Writes the request method and path

Writes the responses table for given swagger operation to file.

Link to this section Functions

Link to this function

find_operation_by_id(swagger, operation_id)

Find the details of an API operation in swagger by operationId

Link to this function

format_resp_body(string)

Pretty-print a JSON response, handling body correctly

Link to this function

group_records(records)

Group a list of tagged records, first by tag, then by operation_id.

Link to this function

resolve_schema_type(swagger, param)

Link to this function

resolve_type(swagger, property_details)

Link to this function

schema_ref_to_link(arg)

Link to this function

tag_record(conn, tags_by_operation_id)

Tag a single record with swagger tag and operation_id.

Link to this function

tag_records(records, swagger)

Populate each test record with private.swagger_tag and private.operation_id from swagger.

Link to this function

write(records, path)

Writes a list of Plug.Conn records to the given file path.

Each Conn should have request and response data populated, and the private.phoenix_controller, private.phoenix_action values set for linking to swagger.

Link to this function

write_action(file, operation_id, records, swagger)

Writes all examples of a given operation (Controller action) to file.

Link to this function

write_authentication(file, swagger)

Writes the authentication details to the given file.

This corresponds to the securityDefinitions section of the swagger document.

Link to this function

write_example(file, record)

Writes a single request/response example to file

Link to this function

write_headers(file, headers)

Write the list of request/response headers

Link to this function

write_model(file, swagger, arg)

Writes a single API model schema to the given file.

Most of the work is delegated to the write_model_properties/3 recurive function. The example json is output before the table just so slate will align them.

Link to this function

write_model_example(file, arg2)

Link to this function

write_model_properties(file, swagger, model_schema, prefix \\ "")

Writes the fields of the given model to file.

prefix is output before each property name to enable nested objects to be flattened.

Link to this function

write_model_property(file, swagger, property, property_details, type, required?)

Link to this function

write_models(file, swagger)

Writes the API request/response model schemas to the given file.

This corresponds to the definitions section of the swagger document. Each top level definition will be written as a table. Nested objects are flattened out to reduce the number of tables being produced.

Link to this function

write_operations_for_tag(file, tag, records_by_operation_id, swagger)

Writes the API details and exampels for operations having the given tag.

tag roughly corresponds to a phoenix controller, eg "Users" records_by_operation_id are the examples collected during tests, grouped by operationId (Controller.action)

Link to this function

write_overview(file, swagger)

Writes the document title and api summary description.

This corresponds to the info section of the swagger document.

Link to this function

write_parameters(file, swagger, _)

Writes the parameters table for given swagger operation to file.

Uses the vendor extension "x-example" to provide example of each parameter. TODO: detailed schema validation rules aren't shown yet (min/max/regex/etc...)

Link to this function

write_request(file, map)

Writes the request method and path

Link to this function

write_responses(file, swagger_operation)

Writes the responses table for given swagger operation to file.

Swagger only allows a single description per status code, which can be limiting when trying to describe all possible error responses. To work around this, add markdown links into the description.