https://github.com/genieframework/swaggermarkdown.jl
https://github.com/genieframework/swaggermarkdown.jl
Last synced: over 1 year ago
JSON representation
- Host: GitHub
- URL: https://github.com/genieframework/swaggermarkdown.jl
- Owner: GenieFramework
- License: mit
- Created: 2021-05-11T22:48:52.000Z (about 5 years ago)
- Default Branch: master
- Last Pushed: 2024-11-18T18:38:29.000Z (over 1 year ago)
- Last Synced: 2025-02-21T15:04:09.153Z (over 1 year ago)
- Language: Julia
- Size: 51.8 KB
- Stars: 11
- Watchers: 3
- Forks: 3
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Julia Swagger Markdown
[](https://codecov.io/gh/jiachengzhang1/SwaggerMarkdown)
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](https://swagger.io/specification/#paths-object), [v2](https://swagger.io/docs/specification/2-0/paths-and-operations/)), and in YAML format.
For more information about OpenAPI Specification, [version 3](https://swagger.io/docs/specification/basic-structure/), [version 2](https://swagger.io/docs/specification/2-0/basic-structure/).
The package is inspired by, and it uses the similar style as [swagger-jsdoc](https://github.com/Surnet/swagger-jsdoc).
## Installation
```julia
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](https://swagger.io/specification/#paths-object), [version 2](https://swagger.io/docs/specification/2-0/paths-and-operations/)), and in YAML format.
```julia
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)`:
```json
{
"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
```julia
optional_fields["servers"] = [Dict("url" => ENV["BASEPATH"])]
openApi = OpenAPI("3.0", info, optional_fields=optional_fields)
```
For OpenAPI 2.0, use the `basePath`optional field as
```julia
optional_fields["basePath"] = ENV["BASEPATH"]
openApi = OpenAPI("3.0", info, optional_fields=optional_fields)
```
### Components
[Components](https://swagger.io/docs/specification/v3_0/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](https://swagger.io/docs/specification/v3_0/using-ref/).
```julia
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.
```julia
@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.