README.md

Julia Swagger Markdown

Swagger Markdown allows you to generate swagger.json for API documentation from the julia source code. The package uses marco to process the markdown that contains an API endpoint's documentation. The markdowon needs to follow the paths described by the OpenAPI Specification (v3, v2), and in YAML format.

For more information about OpenAPI Specification, version 3, version 2.

The package is inspired by, and it uses the similar style as swagger-jsdoc.

Installation

julia> ]
pkg> add SwaggerMarkdown

Usage

Write markdown for the documentation of the API endpoints. The markdowon needs to follow the paths described by the OpenAPI Specification (version 3, version 2), and in YAML format.

using JSON
using SwaggerMarkdown

@swagger """
/doge:
  get:
    description: doge
    responses:
      '200':
        description: Returns a doge.
"""

# the version of the OpenAPI used is required
openApi_version = "2.0"

# the info of the API, title and version of the info are required
info = Dict{String, Any}()
info["title"] = "Doge to the moon"
info["version"] = "1.0.5"

openApi = OpenAPI(openApi_version, info)

swagger_document = build(openApi)
swagger_json = JSON.json(swagger_document)

Note: make sure the the version in the SwaggerMarkdown.OpenAPI matches the version used in markdown.

The json generated by JSON.json(swagger_document):

{
    "swagger": "2.0",
    "paths": {
        "/doge": {
            "get": {
                "responses": {
                    "200": {
                        "description": "Returns a doge."
                    }
                },
                "description": "doge"
            }
        }
    },
    "info": {
        "title": "Doge to the moon",
        "version": "1.0.5"
    }
}

Base path

If your API sits behind a reverse proxy with a base path, you'll need to set the servers optional field as

optional_fields["servers"] = [Dict("url" => ENV["BASEPATH"])]
openApi = OpenAPI("3.0", info, optional_fields=optional_fields)

For OpenAPI 2.0, use the basePathoptional field as

optional_fields["basePath"] = ENV["BASEPATH"]
openApi = OpenAPI("3.0", info, optional_fields=optional_fields)

Components

Components are supported by additional macros.

• @swagger_schemas
• @swagger_parameters
• @swagger_requestBodies
• @swagger_responses
• @swagger_headers
• @swagger_examples
• @swagger_links
• @swagger_callbacks

These can be used anywhere in the code. The following example declares a User schema which can be referenced.

using JSON
using SwaggerMarkdown

@swagger_schemas """
User:
  properties:
    id:
      type: integer
    name:
      type: string
"""

The schema can then be used to describe e.g. the response of an endpoint.

@swagger """
/user:
  get:
    description: Get a user
    responses:
      '200':
        description: Successful retrieval of a user
        schema:
          \$ref: "#/components/schemas/User"
"""

Please note the \ in front of $ref for escaping the $ which is normally used for string interpolation.