使用 Redoc 生成 OpenAPI 文件網站

做法

安裝 Redoc CLI 工具。

1
npm i -g redoc-cli

新增 openapi.yaml 檔。

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
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
openapi: 3.0.3

info:
title: JSONPlaceholder
description: Free fake API for testing and prototyping.
version: 0.1.0

externalDocs:
description: "JSONPlaceholder's guide"
url: https://jsonplaceholder.typicode.com/guide

servers:
- url: https://jsonplaceholder.typicode.com
description: JSONPlaceholder

paths:
"/posts":
get:
tags: ["posts"]
summary: Returns all posts
responses:
"200":
description: All went well
content:
application/json:
schema:
$ref: "#/components/schemas/post"
post:
tags: ["posts"]
summary: Create a new post
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/post"
required: true
responses:
"200":
description: A post was created
content:
application/json:
schema:
$ref: "#/components/schemas/post"
"/posts/{id}":
parameters:
- name: id
in: path
description: ID of the post
required: true
schema:
type: string
get:
tags: ["post"]
summary: Get a single post
responses:
"200":
description: All went well
content:
application/json:
schema:
$ref: "#/components/schemas/post"
"404":
description: Post not found
content:
application/json:
schema:
type: object
properties: {}
put:
tags: ["post"]
summary: Update a post
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/post"
required: true
responses:
"200":
description: All went well
content:
application/json:
schema:
$ref: "#/components/schemas/post"
"404":
description: Post not found
content:
application/json:
schema:
type: object
properties: {}
delete:
tags: ["post"]
summary: Delete a post
responses:
"200":
description: All went well
content:
application/json:
schema:
type: object
properties: {}
"404":
description: Post not found
content:
application/json:
schema:
type: object
properties: {}

components:
schemas:
post:
type: object
properties:
id:
type: number
description: ID of the post
title:
type: string
description: Title of the post
body:
type: string
description: Body of the post
userId:
type: number
description: ID of the user who created the post

生成文件網站。

1
redoc-cli --output index.html build openapi.yaml

參考資料