coder/scripts/apidocgen/markdown-template

Swagger / OpenAPI 2 and OpenAPI 3 template parameters

Note that properties of OpenAPI objects will be in OpenAPI 3.0 form, as Swagger / OpenAPI 2.0 definitions are converted automatically.

Code templates

• method - the HTTP method of the operation (in lower-case)
• methodUpper - the HTTP method of the operation (in upper-case)
• url - the full URL of the operation (including protocol and host)
• consumes[] - an array of MIME-types the operation consumes
• produces[] - an array of MIME-types the operation produces
• operation - the current operation object
• operationId - the current operation id
• opName - the operationId if set, otherwise the method + path
• tags[] - the full list of tags applying to the operation
• security - the security definitions applying to the operation
• resource - the current tag/path object
• parameters[] - an array of parameters for the operation (see below)
• queryString - an example queryString, urlEncoded
• requiredQueryString - an example queryString for required:true parameters
• queryParameters[] - a subset of parameters that are in:query
• requiredParameters[] - a subset of queryParameters that are required:true
• headerParameters[] - a subset of parameters that are in:header
• allHeaders[] - a concatenation of headerParameters and pseudo-parameters Accept and Content-Type, and optionally Authorization (the latter has an isAuth boolean property set true so it can be omitted in templates if desired

Parameter template

• parameters[] - an array of parameters, including the following pseudo-properties
  • shortDesc - a truncated version of the parameter description
  • safeType - a computed version of the parameter type, including Body and schema names
  • originalType - the original type of the parameter
  • exampleValues - an object containing examples for use in code-templates
    • json - example values in JSON compatible syntax
    • object - example values in raw object form (unquoted strings etc)
  • depth - a zero-based indicator of the depth of expanded request body parameters
• enums[] - an array of (parameter)name/value pairs

Responses template

• responses[] - an array of responses, including status and meaning properties

Authentication template

• authenticationStr - a simple string of methods (and scopes where appropriate)
• securityDefinitions[] - an array of applicable securityDefinitions

Schema Property template

• schemaProperties[] - an array of
  • name
  • type
  • required
  • description
• enums[] - an array of (schema property)name/value pairs

Common to all templates

• openapi - the top-level OpenAPI / Swagger document
• header - the front-matter of the Slate/Shins markdown document
• host - the (computed) host of the API
• protocol - the default/first protocol of the API
• baseUrl - the (computed) baseUrl of the API (including protocol and host)
• widdershins - the contents of widdershins package.json