Skip to content

Commit cd12103

Browse files
hirotakahirotaka
authored
Merge pull request #10 from hirotaka/docs/fix-introduction-link-and-add-sample-schema
docs: fix introduction link and add sample OpenAPI schema
2 parents aaea1a3 + 3bd5589 commit cd12103

File tree

4 files changed

+264
-9
lines changed

4 files changed

+264
-9
lines changed

‎docs/.vitepress/en.ts‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,6 @@ export default defineConfig({
99
text: "openapi-vue-query",
1010
base: "/openapi-vue-query",
1111
items: [
12-
{ text: "Introduction", link: "/introduction" },
1312
{ text: "Getting Started", link: "/" },
1413
{ text: "useQuery", link: "/use-query" },
1514
{ text: "useMutation", link: "/use-mutation" },

‎docs/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ hero:
88
actions:
99
- theme: brand
1010
text: Get Started
11-
link: /openapi-vue-query/introduction
11+
link: /openapi-vue-query
1212
- theme: alt
1313
text: View on GitHub
1414
link: https://github.com/hirotaka/openapi-typescript-vue

‎docs/openapi-vue-query/index.md‎

Lines changed: 15 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ It works by using [openapi-fetch](https://openapi-ts.dev/openapi-fetch/) and [op
1919
<script setup lang="ts">
2020
import createFetchClient from "openapi-fetch";
2121
import createClient from "openapi-vue-query";
22-
import type { paths } from "./my-openapi-3-schema"; // generated by openapi-typescript
22+
import type { paths } from "./my-openapi-3-schema.d.ts"; // generated by openapi-typescript
2323
2424
const fetchClient = createFetchClient<paths>({
2525
baseUrl: "https://myapi.dev/v1/",
@@ -69,23 +69,31 @@ Enable [noUncheckedIndexedAccess](https://www.typescriptlang.org/tsconfig#noUnch
6969

7070
:::
7171

72-
Next, generate TypeScript types from your OpenAPI schema using openapi-typescript:
73-
7472
```bash
75-
npx openapi-typescript ./path/to/api/v1.yaml -o ./src/lib/api/v1.d.ts
73+
# Generate types from the sample schema
74+
npx openapi-typescript ./my-openapi-3-schema.yaml -o ./my-openapi-3-schema.d.ts
75+
76+
# Or from your own schema
77+
npx openapi-typescript ./path/to/your/api.yaml -o ./src/lib/api/v1.d.ts
7678
```
7779

7880
## Basic usage
7981

80-
Once your types has been generated from your schema, you can create a [fetch client](./introduction), a vue-query client and start querying your API.
82+
Next, you need an OpenAPI schema to work with. For this tutorial, download our sample blog API schema:
83+
84+
📁 **[Download sample schema: my-openapi-3-schema.yaml](./my-openapi-3-schema.yaml)**
85+
86+
Then generate TypeScript types from the schema using openapi-typescript:
87+
88+
Once your types have been generated from your schema, you can create a [fetch client](./introduction), a vue-query client and start querying your API.
8189

8290
::: code-group
8391

84-
```vue [src/my-component.vue]
92+
```vue [src/MyComponent.vue]
8593
<script setup lang="ts">
8694
import createFetchClient from "openapi-fetch";
8795
import createClient from "openapi-vue-query";
88-
import type { paths } from "./my-openapi-3-schema"; // generated by openapi-typescript
96+
import type { paths } from "./my-openapi-3-schema.d.ts"; // generated by openapi-typescript
8997
9098
const fetchClient = createFetchClient<paths>({
9199
baseUrl: "https://myapi.dev/v1/",

‎docs/openapi-vue-query/my-openapi-3-schema.yaml‎

Lines changed: 248 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,248 @@
1+
openapi: 3.0.3
2+
info:
3+
title: Blog API
4+
description: A simple blog API for demonstrating openapi-vue-query
5+
version: 1.0.0
6+
servers:
7+
- url: https://myapi.dev/v1
8+
description: Production server
9+
10+
paths:
11+
/blogposts/{post_id}:
12+
get:
13+
summary: Get a blog post by ID
14+
description: Retrieve a specific blog post by its ID
15+
parameters:
16+
- name: post_id
17+
in: path
18+
required: true
19+
schema:
20+
type: integer
21+
format: int64
22+
example: 5
23+
description: The ID of the blog post to retrieve
24+
responses:
25+
'200':
26+
description: Blog post retrieved successfully
27+
content:
28+
application/json:
29+
schema:
30+
$ref: '#/components/schemas/BlogPost'
31+
'404':
32+
description: Blog post not found
33+
content:
34+
application/json:
35+
schema:
36+
$ref: '#/components/schemas/Error'
37+
'500':
38+
description: Internal server error
39+
content:
40+
application/json:
41+
schema:
42+
$ref: '#/components/schemas/Error'
43+
44+
/blogposts:
45+
get:
46+
summary: List all blog posts
47+
description: Retrieve a list of all blog posts
48+
parameters:
49+
- name: page
50+
in: query
51+
schema:
52+
type: integer
53+
default: 1
54+
minimum: 1
55+
description: Page number for pagination
56+
- name: limit
57+
in: query
58+
schema:
59+
type: integer
60+
default: 10
61+
minimum: 1
62+
maximum: 100
63+
description: Number of posts per page
64+
responses:
65+
'200':
66+
description: List of blog posts retrieved successfully
67+
content:
68+
application/json:
69+
schema:
70+
type: object
71+
properties:
72+
posts:
73+
type: array
74+
items:
75+
$ref: '#/components/schemas/BlogPost'
76+
pagination:
77+
$ref: '#/components/schemas/Pagination'
78+
'500':
79+
description: Internal server error
80+
content:
81+
application/json:
82+
schema:
83+
$ref: '#/components/schemas/Error'
84+
85+
post:
86+
summary: Create a new blog post
87+
description: Create a new blog post
88+
requestBody:
89+
required: true
90+
content:
91+
application/json:
92+
schema:
93+
$ref: '#/components/schemas/CreateBlogPost'
94+
responses:
95+
'201':
96+
description: Blog post created successfully
97+
content:
98+
application/json:
99+
schema:
100+
$ref: '#/components/schemas/BlogPost'
101+
'400':
102+
description: Invalid request data
103+
content:
104+
application/json:
105+
schema:
106+
$ref: '#/components/schemas/Error'
107+
'500':
108+
description: Internal server error
109+
content:
110+
application/json:
111+
schema:
112+
$ref: '#/components/schemas/Error'
113+
114+
components:
115+
schemas:
116+
BlogPost:
117+
type: object
118+
required:
119+
- id
120+
- title
121+
- content
122+
- author
123+
- created_at
124+
- updated_at
125+
properties:
126+
id:
127+
type: integer
128+
format: int64
129+
example: 5
130+
description: Unique identifier for the blog post
131+
title:
132+
type: string
133+
example: "Getting Started with Vue 3"
134+
description: Title of the blog post
135+
content:
136+
type: string
137+
example: "Vue 3 brings many exciting features..."
138+
description: Content of the blog post
139+
author:
140+
$ref: '#/components/schemas/Author'
141+
tags:
142+
type: array
143+
items:
144+
type: string
145+
example: ["vue", "javascript", "frontend"]
146+
description: Tags associated with the blog post
147+
created_at:
148+
type: string
149+
format: date-time
150+
example: "2023-12-01T10:00:00Z"
151+
description: When the blog post was created
152+
updated_at:
153+
type: string
154+
format: date-time
155+
example: "2023-12-01T10:00:00Z"
156+
description: When the blog post was last updated
157+
158+
CreateBlogPost:
159+
type: object
160+
required:
161+
- title
162+
- content
163+
- author_id
164+
properties:
165+
title:
166+
type: string
167+
example: "Getting Started with Vue 3"
168+
description: Title of the blog post
169+
content:
170+
type: string
171+
example: "Vue 3 brings many exciting features..."
172+
description: Content of the blog post
173+
author_id:
174+
type: integer
175+
format: int64
176+
example: 1
177+
description: ID of the author
178+
tags:
179+
type: array
180+
items:
181+
type: string
182+
example: ["vue", "javascript", "frontend"]
183+
description: Tags associated with the blog post
184+
185+
Author:
186+
type: object
187+
required:
188+
- id
189+
- name
190+
- email
191+
properties:
192+
id:
193+
type: integer
194+
format: int64
195+
example: 1
196+
description: Unique identifier for the author
197+
name:
198+
type: string
199+
example: "John Doe"
200+
description: Name of the author
201+
email:
202+
type: string
203+
format: email
204+
example: "[email protected]"
205+
description: Email address of the author
206+
bio:
207+
type: string
208+
example: "Full-stack developer with 5 years of experience"
209+
description: Short biography of the author
210+
211+
Pagination:
212+
type: object
213+
required:
214+
- page
215+
- limit
216+
- total
217+
- total_pages
218+
properties:
219+
page:
220+
type: integer
221+
example: 1
222+
description: Current page number
223+
limit:
224+
type: integer
225+
example: 10
226+
description: Number of items per page
227+
total:
228+
type: integer
229+
example: 25
230+
description: Total number of items
231+
total_pages:
232+
type: integer
233+
example: 3
234+
description: Total number of pages
235+
236+
Error:
237+
type: object
238+
required:
239+
- message
240+
properties:
241+
message:
242+
type: string
243+
example: "Blog post not found"
244+
description: Error message describing what went wrong
245+
code:
246+
type: string
247+
example: "NOT_FOUND"
248+
description: Error code for programmatic handling

0 commit comments

Comments
 (0)