openapi-markdown/src/openapi_markdown/templates/api_doc_template.md.j2 at main · vrerv/openapi-markdown · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
# {{ spec.info.title }}

{{ spec.info.description }}

# Base URL


| URL | Description |
|-----|-------------|
{% for server in spec.servers -%}
| {{ server.url }} | {{ server.description }} |
{% endfor %}

{% if spec.components and spec.components.securitySchemes -%}

# Authentication

{% with root = spec.components -%}
{% include './_security_scheme.md.j2' -%}
{% endwith -%}
{% endif -%}

# APIs

{% for path, methods in spec.paths.items() -%}

{% for method, operation in methods.items() -%}
## {{ method.upper() }} {{ path }}

{{ operation.summary }}

{% if operation.description and operation.description != operation.summary -%}
{{ operation.description }}
{% endif %}

{% if operation.parameters -%}

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
{% for param in operation.parameters -%}
{% set param_obj = ref_to_schema(param) -%}
| {{ param_obj.name }} | {{ param_obj.schema.type }} | {{ param_obj.required }} | {{ param_obj.description }} |
{% endfor -%}
{% endif %}

{% if operation.requestBody -%}

### Request Body

{% set content = operation.requestBody.content -%}
{% include './_content.md.j2' %}

{% endif -%}

### Responses

{% for status_code, response in operation.responses.items() -%}

#### {{ status_code }}

{% if response.description %}
{{ response.description }}
{% endif %}

{% set content = response.content -%}
{% include './_content.md.j2' %}

{% endfor -%}
{% endfor -%}
{% endfor -%}

{% if spec.components and spec.components.schemas -%}

# Components

{% for schema_name, schema in spec.components.schemas.items() %}

## {{ schema_name }}

{% if schema.description %}
{{ schema.description }}
{% endif %}

{% include './_object_schema.md.j2' -%}
{% endfor -%}

{% endif -%}