SwaggerMarkdown.jl

Author jiachengzhang1
Popularity
0 Stars
Updated Last
1 Year Ago
Started In
May 2021

Julia Swagger Markdown

codecov

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

The package hasn't been published to General yet, so it can be added only through the GitHub. The following commands explain the process.

julia> ]
pkg> add https://github.com/jiachengzhang1/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"
    }
}

Used By Packages

No packages found.