Bureaucrat.SwaggerSlateMarkdownWriter (bureaucrat v0.2.10)
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: Iffalse, will not render the plaintext version of request/response examples. Defaults totrue
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
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_schema_type(swagger, param)
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, 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...)
write_request(file, map)
Writes the request method and path
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.