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)