Skip to content

Commit e30ecda

Browse files
DevRohit06DevRohit06
committed
Add API documentation for user and post management endpoints
- Created documentation for retrieving users by ID and listing all users. - Added endpoints for creating, updating, and deleting users. - Documented the creation of blog posts and retrieving posts by ID. - Implemented error response handling and request body specifications. - Generated OpenAPI specification for the API endpoints. - Enhanced API reference pages with interactive playgrounds for testing.
1 parent c864871 commit e30ecda

13 files changed

Lines changed: 1577 additions & 51 deletions

‎api/delete-users-id.mdx‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
---
2+
title: Delete User
3+
description: Permanently delete a user from the system
4+
api: DELETE /users/{id}
5+
baseUrl: https://jsonplaceholder.typicode.com
6+
auth: bearer
7+
layout: '@/layouts/APIEndpointLayout.astro'
8+
---
9+
10+
## Overview
11+
12+
Permanently deletes a user from the system. This action cannot be undone.
13+
14+
## Authorization
15+
16+
<Alert type="danger">
17+
This is a destructive operation that requires authentication. Use with caution.
18+
</Alert>
19+
20+
## Path Parameters
21+
22+
<ParamTable type="path">
23+
<Param name="id" type="integer" required>
24+
The unique identifier of the user to delete
25+
</Param>
26+
</ParamTable>
27+
28+
## Response
29+
30+
Returns an empty object on successful deletion.
31+
32+
```json
33+
{}
34+
```
35+
36+
## Error Responses
37+
38+
| Status | Description |
39+
|--------|-------------|
40+
| `401` | Unauthorized - missing or invalid authentication |
41+
| `404` | User not found |
42+
43+
## Usage Notes
44+
45+
<Steps>
46+
<Step title="Verify User Exists">
47+
Before deleting, you may want to verify the user exists using the GET endpoint.
48+
</Step>
49+
<Step title="Handle Dependencies">
50+
Ensure any posts or comments associated with this user are handled appropriately.
51+
</Step>
52+
<Step title="Confirm Deletion">
53+
This operation is irreversible. Consider implementing a confirmation step in your UI.
54+
</Step>
55+
</Steps>

‎api/get-posts-id-comments.mdx‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
---
2+
title: Get Post Comments
3+
description: Retrieve all comments for a specific post
4+
api: GET /posts/{id}/comments
5+
baseUrl: https://jsonplaceholder.typicode.com
6+
layout: '@/layouts/APIEndpointLayout.astro'
7+
---
8+
9+
## Overview
10+
11+
Retrieves all comments associated with a specific blog post.
12+
13+
## Path Parameters
14+
15+
<ParamTable type="path">
16+
<Param name="id" type="integer" required>
17+
The ID of the post to get comments for
18+
</Param>
19+
</ParamTable>
20+
21+
## Response
22+
23+
Returns an array of comment objects.
24+
25+
<ResponseField name="id" type="integer">
26+
Unique identifier for the comment
27+
</ResponseField>
28+
29+
<ResponseField name="postId" type="integer">
30+
ID of the post this comment belongs to
31+
</ResponseField>
32+
33+
<ResponseField name="name" type="string">
34+
Title or subject of the comment
35+
</ResponseField>
36+
37+
<ResponseField name="email" type="string">
38+
Email address of the commenter
39+
</ResponseField>
40+
41+
<ResponseField name="body" type="string">
42+
Content of the comment
43+
</ResponseField>
44+
45+
## Example Response
46+
47+
```json
48+
[
49+
{
50+
"postId": 1,
51+
"id": 1,
52+
"name": "id labore ex et quam laborum",
53+
"email": "Eliseo@gardner.biz",
54+
"body": "laudantium enim quasi est quidem magnam voluptate ipsam eos\ntempora quo necessitatibus\ndolor quam autem quasi\nreiciendis et nam sapiente accusantium"
55+
},
56+
{
57+
"postId": 1,
58+
"id": 2,
59+
"name": "quo vero reiciendis velit similique earum",
60+
"email": "Jayne_Kuhic@sydney.com",
61+
"body": "est natus enim nihil est dolore omnis voluptatem numquam\net omnis occaecati quod ullam at\nvoluptatem error expedita pariatur\nnihil sint nostrum voluptatem reiciendis et"
62+
}
63+
]
64+
```
65+
66+
## Related Endpoints
67+
68+
<Card title="Get Post Details" href="/api/get-posts-id" icon="lucide:file-text">
69+
View the full post that these comments belong to
70+
</Card>
71+
72+
## Error Responses
73+
74+
| Status | Description |
75+
|--------|-------------|
76+
| `404` | Post not found - the specified post ID does not exist |

‎api/get-posts-id.mdx‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
---
2+
title: Get Post by ID
3+
description: Retrieve a single blog post by its ID
4+
api: GET /posts/{id}
5+
baseUrl: https://jsonplaceholder.typicode.com
6+
layout: '@/layouts/APIEndpointLayout.astro'
7+
---
8+
9+
## Overview
10+
11+
Retrieves detailed information about a specific blog post.
12+
13+
## Path Parameters
14+
15+
<ParamTable type="path">
16+
<Param name="id" type="integer" required>
17+
The unique identifier of the post to retrieve
18+
</Param>
19+
</ParamTable>
20+
21+
## Response
22+
23+
<ResponseField name="id" type="integer">
24+
Unique identifier for the post
25+
</ResponseField>
26+
27+
<ResponseField name="userId" type="integer">
28+
ID of the user who created the post
29+
</ResponseField>
30+
31+
<ResponseField name="title" type="string">
32+
Title of the post
33+
</ResponseField>
34+
35+
<ResponseField name="body" type="string">
36+
Full content of the post
37+
</ResponseField>
38+
39+
## Example Response
40+
41+
```json
42+
{
43+
"userId": 1,
44+
"id": 1,
45+
"title": "sunt aut facere repellat provident occaecati excepturi optio reprehenderit",
46+
"body": "quia et suscipit\nsuscipit recusandae consequuntur expedita et cum\nreprehenderit molestiae ut ut quas totam\nnostrum rerum est autem sunt rem eveniet architecto"
47+
}
48+
```
49+
50+
## Related Endpoints
51+
52+
<CardGroup cols={2}>
53+
<Card title="Get Comments" href="/api/get-posts-id-comments" icon="lucide:message-circle">
54+
Retrieve all comments for this post
55+
</Card>
56+
<Card title="List All Posts" href="/api/get-posts" icon="lucide:list">
57+
View all posts with filtering options
58+
</Card>
59+
</CardGroup>
60+
61+
## Error Responses
62+
63+
| Status | Description |
64+
|--------|-------------|
65+
| `404` | Post not found - the specified ID does not exist |

‎api/get-posts.mdx‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
---
2+
title: List Posts
3+
description: Retrieve a list of all blog posts
4+
api: GET /posts
5+
baseUrl: https://jsonplaceholder.typicode.com
6+
layout: '@/layouts/APIEndpointLayout.astro'
7+
---
8+
9+
## Overview
10+
11+
Returns a list of all blog posts. Supports filtering by user ID and pagination.
12+
13+
## Query Parameters
14+
15+
<ParamTable type="query">
16+
<Param name="userId" type="integer">
17+
Filter posts by a specific user ID
18+
</Param>
19+
<Param name="_limit" type="integer" default="10">
20+
Maximum number of posts to return
21+
</Param>
22+
<Param name="_start" type="integer" default="0">
23+
Number of posts to skip for pagination
24+
</Param>
25+
</ParamTable>
26+
27+
## Response
28+
29+
Returns an array of post objects.
30+
31+
<ResponseField name="id" type="integer">
32+
Unique identifier for the post
33+
</ResponseField>
34+
35+
<ResponseField name="userId" type="integer">
36+
ID of the user who created the post
37+
</ResponseField>
38+
39+
<ResponseField name="title" type="string">
40+
Title of the post
41+
</ResponseField>
42+
43+
<ResponseField name="body" type="string">
44+
Content of the post
45+
</ResponseField>
46+
47+
## Example Response
48+
49+
```json
50+
[
51+
{
52+
"userId": 1,
53+
"id": 1,
54+
"title": "sunt aut facere repellat provident occaecati excepturi optio reprehenderit",
55+
"body": "quia et suscipit\nsuscipit recusandae consequuntur expedita..."
56+
},
57+
{
58+
"userId": 1,
59+
"id": 2,
60+
"title": "qui est esse",
61+
"body": "est rerum tempore vitae\nsequi sint nihil reprehenderit dolor..."
62+
}
63+
]
64+
```
65+
66+
## Filtering Examples
67+
68+
### Get posts by a specific user
69+
70+
```bash
71+
GET /posts?userId=1
72+
```
73+
74+
### Paginate results
75+
76+
```bash
77+
GET /posts?_start=10&_limit=5
78+
```

‎api/get-users-id.mdx‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
---
2+
title: Get User by ID
3+
description: Retrieve a single user by their unique identifier
4+
api: GET /users/{id}
5+
baseUrl: https://jsonplaceholder.typicode.com
6+
layout: '@/layouts/APIEndpointLayout.astro'
7+
---
8+
9+
## Overview
10+
11+
Retrieves detailed information about a specific user by their ID.
12+
13+
## Path Parameters
14+
15+
<ParamTable type="path">
16+
<Param name="id" type="integer" required>
17+
The unique identifier of the user to retrieve
18+
</Param>
19+
</ParamTable>
20+
21+
## Response
22+
23+
<ResponseField name="id" type="integer">
24+
Unique identifier for the user
25+
</ResponseField>
26+
27+
<ResponseField name="name" type="string">
28+
Full name of the user
29+
</ResponseField>
30+
31+
<ResponseField name="username" type="string">
32+
Unique username
33+
</ResponseField>
34+
35+
<ResponseField name="email" type="string">
36+
Email address
37+
</ResponseField>
38+
39+
<ResponseField name="address" type="object" expandable>
40+
Physical address of the user
41+
42+
<ResponseField name="street" type="string">
43+
Street address
44+
</ResponseField>
45+
<ResponseField name="suite" type="string">
46+
Apartment or suite number
47+
</ResponseField>
48+
<ResponseField name="city" type="string">
49+
City name
50+
</ResponseField>
51+
<ResponseField name="zipcode" type="string">
52+
Postal code
53+
</ResponseField>
54+
<ResponseField name="geo" type="object">
55+
Geographic coordinates (lat, lng)
56+
</ResponseField>
57+
</ResponseField>
58+
59+
<ResponseField name="phone" type="string">
60+
Phone number
61+
</ResponseField>
62+
63+
<ResponseField name="website" type="string">
64+
Personal website URL
65+
</ResponseField>
66+
67+
<ResponseField name="company" type="object" expandable>
68+
Company information
69+
70+
<ResponseField name="name" type="string">
71+
Company name
72+
</ResponseField>
73+
<ResponseField name="catchPhrase" type="string">
74+
Company slogan
75+
</ResponseField>
76+
<ResponseField name="bs" type="string">
77+
Business description
78+
</ResponseField>
79+
</ResponseField>
80+
81+
## Example Response
82+
83+
```json
84+
{
85+
"id": 1,
86+
"name": "Leanne Graham",
87+
"username": "Bret",
88+
"email": "Sincere@april.biz",
89+
"address": {
90+
"street": "Kulas Light",
91+
"suite": "Apt. 556",
92+
"city": "Gwenborough",
93+
"zipcode": "92998-3874",
94+
"geo": {
95+
"lat": "-37.3159",
96+
"lng": "81.1496"
97+
}
98+
},
99+
"phone": "1-770-736-8031 x56442",
100+
"website": "hildegard.org",
101+
"company": {
102+
"name": "Romaguera-Crona",
103+
"catchPhrase": "Multi-layered client-server neural-net",
104+
"bs": "harness real-time e-markets"
105+
}
106+
}
107+
```
108+
109+
## Error Responses
110+
111+
| Status | Description |
112+
|--------|-------------|
113+
| `404` | User not found - the specified ID does not exist |

0 commit comments

Comments
 (0)