Skip to content

Commit 0ad6110

Browse files
zduneckizdunecki
committed
feat: better openapi example output
1 parent 9a36bbe commit 0ad6110

5 files changed

Lines changed: 396 additions & 7 deletions

File tree

‎packages/xyd-openapi/__fixtures__/6.codeSamples/output.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@
2121
"examples": {
2222
"groups": [
2323
{
24-
"description": "Example request",
24+
"description": "List all users",
2525
"examples": [
2626
{
2727
"codeblock": {

‎packages/xyd-openapi/__fixtures__/7.examples/input.yaml‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
openapi: 3.0.0
2+
info:
3+
title: Sample API
4+
description: Optional multiline or single-line description in [CommonMark](http://commonmark.org/help/) or HTML.
5+
version: 0.1.9
6+
servers:
7+
- url: http://api.example.com/v1
8+
description: Optional server description, e.g. Main (production) server
9+
- url: http://staging-api.example.com
10+
description: Optional server description, e.g. Internal staging server for testing
11+
paths:
12+
/users:
13+
get:
14+
summary: Returns a list of users
15+
description: Optional extended description in CommonMark or HTML.
16+
x-codeSamples:
17+
- lang: bash
18+
label: List all users
19+
source: |
20+
curl -X GET https://api.example.com/v1/users
21+
22+
- lang: javascript
23+
label: List all users
24+
source: |
25+
const api = require('api-client');
26+
api.users.list();
27+
parameters:
28+
- name: limit
29+
in: query
30+
description: Maximum number of items to return
31+
required: true
32+
schema:
33+
type: integer
34+
default: 20
35+
- name: offset
36+
in: query
37+
description: Number of items to skip
38+
required: false
39+
schema:
40+
type: integer
41+
default: 0
42+
responses:
43+
'200':
44+
description: A JSON array of users
45+
content:
46+
application/json:
47+
schema:
48+
type: array
49+
items:
50+
$ref: '#/components/schemas/User'
51+
examples:
52+
json:
53+
summary: A sample JSON response
54+
value: {
55+
id: 1,
56+
username: 'John Doe',
57+
}
58+
components:
59+
schemas:
60+
User:
61+
type: object
62+
required:
63+
- id
64+
- username
65+
properties:
66+
id:
67+
type: integer
68+
format: int64
69+
username:
70+
type: string
71+
email:
72+
type: string
73+
format: email
74+
status:
75+
type: string
76+
enum: [ active, inactive ]
77+
createdAt:
78+
type: string
79+
format: date-time
80+
updatedAt:
81+
type: string
82+
format: date-time

‎packages/xyd-openapi/__fixtures__/7.examples/output.json‎

Lines changed: 294 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,294 @@
1+
[
2+
{
3+
"title": "Returns a list of users",
4+
"canonical": "returns-a-list-of-users",
5+
"description": "Optional extended description in CommonMark or HTML.",
6+
"type": "rest_get",
7+
"category": "rest",
8+
"context": {
9+
"method": "get",
10+
"path": "/users",
11+
"fullPath": "http:/api.example.com/v1/users",
12+
"group": [
13+
""
14+
],
15+
"scopes": []
16+
},
17+
"examples": {
18+
"groups": [
19+
{
20+
"description": "List all users",
21+
"examples": [
22+
{
23+
"codeblock": {
24+
"title": "List all users",
25+
"tabs": [
26+
{
27+
"title": "bash",
28+
"language": "bash",
29+
"code": "curl -X GET https://api.example.com/v1/users\n"
30+
},
31+
{
32+
"title": "javascript",
33+
"language": "javascript",
34+
"code": "const api = require('api-client');\napi.users.list();\n"
35+
}
36+
]
37+
}
38+
}
39+
]
40+
},
41+
{
42+
"description": "A sample JSON response",
43+
"examples": [
44+
{
45+
"codeblock": {
46+
"title": "200",
47+
"tabs": [
48+
{
49+
"title": "application/json",
50+
"language": "json",
51+
"code": "{\n \"id\": 1,\n \"username\": \"John Doe\"\n}"
52+
}
53+
]
54+
}
55+
}
56+
]
57+
}
58+
]
59+
},
60+
"definitions": [
61+
{
62+
"title": "Query parameters",
63+
"properties": [
64+
{
65+
"name": "limit",
66+
"type": "integer",
67+
"description": "Maximum number of items to return",
68+
"meta": [
69+
{
70+
"name": "required",
71+
"value": "true"
72+
},
73+
{
74+
"name": "defaults",
75+
"value": 20
76+
}
77+
]
78+
},
79+
{
80+
"name": "offset",
81+
"type": "integer",
82+
"description": "Number of items to skip",
83+
"meta": [
84+
{
85+
"name": "defaults",
86+
"value": 0
87+
}
88+
]
89+
}
90+
]
91+
},
92+
{
93+
"title": "Response",
94+
"variants": [
95+
{
96+
"title": "200",
97+
"description": "A JSON array of users",
98+
"properties": [],
99+
"rootProperty": {
100+
"type": "$$array",
101+
"properties": [
102+
{
103+
"name": "id",
104+
"type": "integer",
105+
"description": "",
106+
"meta": [
107+
{
108+
"name": "required",
109+
"value": "true"
110+
}
111+
]
112+
},
113+
{
114+
"name": "username",
115+
"type": "string",
116+
"description": "",
117+
"meta": [
118+
{
119+
"name": "required",
120+
"value": "true"
121+
}
122+
]
123+
},
124+
{
125+
"name": "email",
126+
"type": "string",
127+
"description": "",
128+
"meta": []
129+
},
130+
{
131+
"name": "status",
132+
"type": "$$enum",
133+
"description": "",
134+
"meta": [
135+
{
136+
"name": "enum-type",
137+
"value": "string"
138+
}
139+
],
140+
"properties": [
141+
{
142+
"name": "active",
143+
"type": "string",
144+
"description": "",
145+
"meta": []
146+
},
147+
{
148+
"name": "inactive",
149+
"type": "string",
150+
"description": "",
151+
"meta": []
152+
}
153+
]
154+
},
155+
{
156+
"name": "createdAt",
157+
"type": "string",
158+
"description": "",
159+
"meta": []
160+
},
161+
{
162+
"name": "updatedAt",
163+
"type": "string",
164+
"description": "",
165+
"meta": []
166+
}
167+
]
168+
},
169+
"meta": [
170+
{
171+
"name": "status",
172+
"value": "200"
173+
},
174+
{
175+
"name": "contentType",
176+
"value": "application/json"
177+
},
178+
{
179+
"name": "definitionDescription",
180+
"value": ""
181+
}
182+
]
183+
}
184+
],
185+
"properties": []
186+
}
187+
]
188+
},
189+
{
190+
"title": "User",
191+
"description": "",
192+
"canonical": "objects/User",
193+
"definitions": [
194+
{
195+
"title": "User",
196+
"properties": [
197+
{
198+
"name": "id",
199+
"type": "integer",
200+
"description": "",
201+
"meta": [
202+
{
203+
"name": "required",
204+
"value": "true"
205+
}
206+
]
207+
},
208+
{
209+
"name": "username",
210+
"type": "string",
211+
"description": "",
212+
"meta": [
213+
{
214+
"name": "required",
215+
"value": "true"
216+
}
217+
]
218+
},
219+
{
220+
"name": "email",
221+
"type": "string",
222+
"description": "",
223+
"meta": []
224+
},
225+
{
226+
"name": "status",
227+
"type": "$$enum",
228+
"description": "",
229+
"meta": [
230+
{
231+
"name": "enum-type",
232+
"value": "string"
233+
}
234+
],
235+
"properties": [
236+
{
237+
"name": "active",
238+
"type": "string",
239+
"description": "",
240+
"meta": []
241+
},
242+
{
243+
"name": "inactive",
244+
"type": "string",
245+
"description": "",
246+
"meta": []
247+
}
248+
]
249+
},
250+
{
251+
"name": "createdAt",
252+
"type": "string",
253+
"description": "",
254+
"meta": []
255+
},
256+
{
257+
"name": "updatedAt",
258+
"type": "string",
259+
"description": "",
260+
"meta": []
261+
}
262+
],
263+
"meta": []
264+
}
265+
],
266+
"examples": {
267+
"groups": [
268+
{
269+
"description": "Example",
270+
"examples": [
271+
{
272+
"codeblock": {
273+
"tabs": [
274+
{
275+
"title": "json",
276+
"language": "json",
277+
"code": "{\n \"id\": 0,\n \"username\": \"\",\n \"email\": \"\",\n \"status\": \"\",\n \"createdAt\": \"\",\n \"updatedAt\": \"\"\n}"
278+
}
279+
]
280+
}
281+
}
282+
]
283+
}
284+
]
285+
},
286+
"type": "rest_component_schema",
287+
"context": {
288+
"componentSchema": "User",
289+
"group": [
290+
"Objects"
291+
]
292+
}
293+
}
294+
]

0 commit comments

Comments
 (0)