openapi-spec-generator

Name: openapi-spec-generator
Author: LambdaTest

335stars67forks

How to install openapi-spec-generator?

lambdatest/agent-skills/openapi-spec-generator

$npx -y skills add LambdaTest/agent-skills --skill openapi-spec-generator

Installs into the current project.

Summary

Generate complete, production-ready OpenAPI 3.x and Swagger 2.0 specifications from natural language descriptions, code, or partial specs. Use this skill whenever the user mentions OpenAPI, Swagger, API spec, REST API documentation, YAML/JSON API schema, endpoint documentation, A

Files · 1

View on GitHub

SKILL.md

1	# OpenAPI / Swagger Specification Generator
2
3	Generate complete, valid OpenAPI 3.x or Swagger 2.0 specifications from descriptions, code, or partial specs.
4
5	## Workflow
6
7	### Step 1 — Gather Context
8
9	Before writing any YAML/JSON, ask (or infer from context) the following:
10
11	\| Question \| Why it matters \|
12	\|---\|---\|
13	\| OpenAPI 3.x or Swagger 2.0? \| Different `info`, `servers`/`host`, `components`/`definitions` structure \|
14	\| Output format: YAML or JSON? \| YAML default unless user specifies JSON \|
15	\| What does this API do? \| Sets `info.title`, `info.description`, tags \|
16	\| List of endpoints (or code to extract from)? \| Core paths object \|
17	\| Authentication type(s)? \| `securitySchemes` — see reference \|
18	\| Common data models or entities? \| `components/schemas` / `definitions` \|
19	\| Any existing partial spec to extend? \| Merge rather than overwrite \|
20
21	If the user provides code (Express routes, FastAPI, Django URLs, Spring controllers, etc.), extract endpoints automatically — do not ask what the user already told you.
22
23	### Step 2 — Build the Spec
24
25	Follow the structure guide for the chosen version. Always produce a complete, valid spec — never leave placeholder comments like `# TODO: add schema`.
26
27	#### OpenAPI 3.x Skeleton
28
29	```yaml
30	openapi: "3.1.0"
31	info:
32	title: <API Title>
33	version: "1.0.0"
34	description: <Short description>
35	contact:
36	name: <Team or Author>
37	email: <contact@example.com>
38	servers:
39	- url: https://api.example.com/v1
40	description: Production
41	- url: https://staging-api.example.com/v1
42	description: Staging
43	tags:
44	- name: <Tag>
45	description: <Tag description>
46	paths:
47	/resource:
48	get:
49	summary: List resources
50	operationId: listResources
51	tags: [<Tag>]
52	parameters: []
53	responses:
54	"200":
55	description: Success
56	content:
57	application/json:
58	schema:
59	$ref: "#/components/schemas/ResourceList"
60	example:
61	items: []
62	total: 0
63	"401":
64	$ref: "#/components/responses/Unauthorized"
65	"500":
66	$ref: "#/components/responses/InternalError"
67	security:
68	- BearerAuth: []
69	components:
70	schemas: {}
71	responses:
72	Unauthorized:
73	description: Authentication required
74	content:
75	application/json:
76	schema:
77	$ref: "#/components/schemas/Error"
78	InternalError:
79	description: Internal server error
80	content:
81	application/json:
82	schema:
83	$ref: "#/components/schemas/Error"
84	securitySchemes: {}
85	```
86
87	#### Swagger 2.0 Skeleton
88
89	```yaml
90	swagger: "2.0"
91	info:
92	title: <API Title>
93	version: "1.0.0"
94	description: <Short description>
95	host: api.example.com
96	basePath: /v1
97	schemes: [https]
98	consumes: [application/json]
99	produces: [application/json]
100	tags: []
101	paths: {}
102	definitions: {}
103	securityDefinitions: {}
104	```
105
106	### Step 3 — Schemas and Models
107
108	- Always use `$ref` for any schema used in more than one place.
109	- Include `example` or `examples` on every schema and response body.
110	- Mark required fields with the `required` array.
111	- Use `nullable: true` (OAS 3.0) or `x-nullable: true` (Swagger 2.0) for optional nullable fields.
112	- Prefer `format` keywords: `int32`, `int64`, `float`, `date`, `date-time`, `uuid`, `email`, `uri`, `byte`, `binary`.
113
114	Common schema patterns:
115
116	```yaml
117	# Pagination wrapper
118	PagedResult:
119	type: object
120	required: [items, total, page, pageSize]
121	properties:
122	items:
123	type: array
124	items:
125	$ref: "#/components/schemas/Resource"
126	total:
127	type: integer
128	format: int64
129	example: 100
130	page:
131	type: integer
132	format: int32
133	example: 1
134	pageSize:
135	type: integer
136	format: int32
137	example: 20
138
139	# Standard error
140	Error:
141	type: object
142	required: [code, message]
143	properties:
144	code:
145	type: string
146	example: RESOURCE_NOT_FOUND
147	message:
148	type: string
149	example: The requested resource was not found.
150	details:
151	type: object

People who liked this also viewed

6 picks

Type

openapi-spec-generator

335stars67forks

View on GitHub

How to install openapi-spec-generator?

lambdatest/agent-skills/openapi-spec-generator

$npx -y skills add LambdaTest/agent-skills --skill openapi-spec-generator

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# OpenAPI / Swagger Specification Generator
2
3	Generate complete, valid OpenAPI 3.x or Swagger 2.0 specifications from descriptions, code, or partial specs.
4
5	## Workflow
6
7	### Step 1 — Gather Context
8
9	Before writing any YAML/JSON, ask (or infer from context) the following:
10
11	\| Question \| Why it matters \|
12	\|---\|---\|
13	\| OpenAPI 3.x or Swagger 2.0? \| Different `info`, `servers`/`host`, `components`/`definitions` structure \|
14	\| Output format: YAML or JSON? \| YAML default unless user specifies JSON \|
15	\| What does this API do? \| Sets `info.title`, `info.description`, tags \|
16	\| List of endpoints (or code to extract from)? \| Core paths object \|
17	\| Authentication type(s)? \| `securitySchemes` — see reference \|
18	\| Common data models or entities? \| `components/schemas` / `definitions` \|
19	\| Any existing partial spec to extend? \| Merge rather than overwrite \|
20
21	If the user provides code (Express routes, FastAPI, Django URLs, Spring controllers, etc.), extract endpoints automatically — do not ask what the user already told you.
22
23	### Step 2 — Build the Spec
24
25	Follow the structure guide for the chosen version. Always produce a complete, valid spec — never leave placeholder comments like `# TODO: add schema`.
26
27	#### OpenAPI 3.x Skeleton
28
29	```yaml
30	openapi: "3.1.0"
31	info:
32	title: <API Title>
33	version: "1.0.0"
34	description: <Short description>
35	contact:
36	name: <Team or Author>
37	email: <contact@example.com>
38	servers:
39	- url: https://api.example.com/v1
40	description: Production
41	- url: https://staging-api.example.com/v1
42	description: Staging
43	tags:
44	- name: <Tag>
45	description: <Tag description>
46	paths:
47	/resource:
48	get:
49	summary: List resources
50	operationId: listResources
51	tags: [<Tag>]
52	parameters: []
53	responses:
54	"200":
55	description: Success
56	content:
57	application/json:
58	schema:
59	$ref: "#/components/schemas/ResourceList"
60	example:
61	items: []
62	total: 0
63	"401":
64	$ref: "#/components/responses/Unauthorized"
65	"500":
66	$ref: "#/components/responses/InternalError"
67	security:
68	- BearerAuth: []
69	components:
70	schemas: {}
71	responses:
72	Unauthorized:
73	description: Authentication required
74	content:
75	application/json:
76	schema:
77	$ref: "#/components/schemas/Error"
78	InternalError:
79	description: Internal server error
80	content:
81	application/json:
82	schema:
83	$ref: "#/components/schemas/Error"
84	securitySchemes: {}
85	```
86
87	#### Swagger 2.0 Skeleton
88
89	```yaml
90	swagger: "2.0"
91	info:
92	title: <API Title>
93	version: "1.0.0"
94	description: <Short description>
95	host: api.example.com
96	basePath: /v1
97	schemes: [https]
98	consumes: [application/json]
99	produces: [application/json]
100	tags: []
101	paths: {}
102	definitions: {}
103	securityDefinitions: {}
104	```
105
106	### Step 3 — Schemas and Models
107
108	- Always use `$ref` for any schema used in more than one place.
109	- Include `example` or `examples` on every schema and response body.
110	- Mark required fields with the `required` array.
111	- Use `nullable: true` (OAS 3.0) or `x-nullable: true` (Swagger 2.0) for optional nullable fields.
112	- Prefer `format` keywords: `int32`, `int64`, `float`, `date`, `date-time`, `uuid`, `email`, `uri`, `byte`, `binary`.
113
114	Common schema patterns:
115
116	```yaml
117	# Pagination wrapper
118	PagedResult:
119	type: object
120	required: [items, total, page, pageSize]
121	properties:
122	items:
123	type: array
124	items:
125	$ref: "#/components/schemas/Resource"
126	total:
127	type: integer
128	format: int64
129	example: 100
130	page:
131	type: integer
132	format: int32
133	example: 1
134	pageSize:
135	type: integer
136	format: int32
137	example: 20
138
139	# Standard error
140	Error:
141	type: object
142	required: [code, message]
143	properties:
144	code:
145	type: string
146	example: RESOURCE_NOT_FOUND
147	message:
148	type: string
149	example: The requested resource was not found.
150	details:
151	type: object

People who liked this also viewed

6 picks

Type