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 the details of an API operation in swagger by operationId
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.
Each Conn should have request and response data populated, and the private.phoenix_controller, private.phoenix_action values set for linking to swagger.
Writes all examples of a given operation (Controller action) to file.
Writes the authentication details to the given file.
This corresponds to the securityDefinitions section of the swagger document.
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.
Writes the fields of the given model to file.
prefix is output before each property name to enable nested objects to be flattened.
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.
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)
Writes the document title and api summary description.
This corresponds to the info section of the swagger document.
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…)
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.