Julia Swagger UI
Want to use Swagger UI in Julia? This package has your back!
Inspired by swagger-ui-express, the package auto-generates Swagger UI based on swagger.json
. The generated API documentation can be served as an endpoint using package such as Genie.jl.
Pre-built swagger-ui is used. Because swagger-ui is implemented in Node.js, all pre-built files and assets are included in the dist folder for serving. (Open an issue if there are better ways to do this.)
Installation
julia> ]
pkg> add SwagUI
Usage
Genie simple setup
using Genie, Genie.Router
using JSON
using SwagUI
# use a swagger json from the local machine
swagger_document = JSON.parsefile("./swagger.json")
route("/docs") do
render_swagger(swagger_document)
end
Swagger Markdown
Inegrate withusing Genie, Genie.Router
using JSON
using SwagUI
using SwaggerMarkdown
@swagger """
/doge:
get:
description: Doge to the moon!
responses:
'200':
description: Doge to the moon!!.
"""
route("/doge") do
JSON.json("Doge to the moon!!")
end
# build a swagger document from markdown
info = Dict{String, Any}()
info["title"] = "Swagger Petstore"
info["version"] = "1.0.5"
openApi = OpenAPI("2.0", info)
swagger_document = build(openApi)
route("/docs") do
render_swagger(swagger_document)
end
up(8001, async = false)
SwaggerMarkdown builds the swagger document from markdown comments in the code. It returns a swagger_document::Dict{String, Any}
that can be used by SwaggerUI.render_swagger
to render the API documentation as Swagger's fashion.
Configuration & Customization
Swagger Explorer
The explorer can be turned off through setting the Options.show_explorer
to false
. It's turned on, i.e. Options.show_explorer = true
by default.
using Genie, Genie.Router
using JSON
using SwagUI
swagger_document = JSON.parsefile("./swagger.json")
# turn off the explorer
options = Options()
options.show_explorer = false
route("/docs") do
render_swagger(swagger_document, options=options)
end
Custom swagger options
Swagger UI can be configured by setting Options.swagger_options::Dict{String, Any}
. The key is the name of the configuration while the value is the setting. More details about configuration can be found through the Official Swagger UI Configuration page. The example below sets the URL pointing to API definition to https://petstore.swagger.io/v2/swagger.json
.
using Genie, Genie.Router
using JSON
using SwagUI
# set the URL pointing to API definition
options = Options()
options.swagger_options["url"] = "https://petstore.swagger.io/v2/swagger.json"
route("/docs") do
# if swagger_options["url"] or swagger_options["urls"] is set,
# swagger_document is not needed
render_swagger(nothing, options=options)
end
Custom CSS
Set Options.custom_css
to a custom CSS as String
.
using Genie, Genie.Router
using JSON
using SwagUI
swagger_document = JSON.parsefile("./swagger.json")
# set custom css using options
options = Options()
options.custom_css = ".swagger-ui .topbar { display: none }"
route("/docs") do
render_swagger(swagger_document, options=options)
end
TODO
More examples