bureaucrat v0.2.2 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.

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 responses table for given swagger operation to file

Functions

find_operation_by_id(swagger, operation_id)

Find the details of an API operation in swagger by operationId

format_resp_body(string)

Pretty-print a JSON response, handling body correctly

group_records(records)

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

resolve_type(swagger, property_details)
schema_ref_to_link(arg)
tag_record(conn, tags_by_operation_id)

Tag a single record with swagger tag and operation_id.

tag_records(records, swagger)

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

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.

write_action(file, operation_id, records, swagger)

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

write_authentication(file, swagger)

Writes the authentication details to the given file.

This corresponds to the securityDefinitions section of the swagger document.

write_example(file, record)

Writes a single request/response example to file

write_headers(file, headers)

Write the list of request/response headers

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.

write_model_example(file, arg2)
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.

write_model_property(file, swagger, property, property_details, type, required?)
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.

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)

write_overview(file, swagger)

Writes the document title and api summary description.

This corresponds to the info section of the swagger document.

write_parameters(file, _)

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…)

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.