Ontwerp en Genereer Voorbeeldverzoeken en Antwoorden voor Mijn REST API Documentatie met Swagger of Redoc
description
Met deze prompt kan ik mijn REST API documentatie verrijken met concrete en realistische voorbeelden van verzoeken en antwoorden, wat het begrip en de adoptie van mijn API door ontwikkelaars aanzienlijk verbetert. Dit lost het probleem van onduidelijke of ontbrekende voorbeelden op en biedt een betere gebruikerservaring dan documentatie zonder voorbeelden.
prompt
try_prompt
Help me voorbeeldverzoeken en voorbeeldantwoorden te ontwerpen en genereren voor mijn REST API documentatie met behulp van <kies Swagger of Redoc>. API Naam: <voer de naam van mijn API in>. Beschrijf de belangrijkste API-eindpunten waarvoor ik voorbeeld ... more
generate_helper
...
tags
ai_answers
provider: openai
model: gpt-4.1-nano
Natuurlijk! Hier zijn gestructureerde voorbeeldverzoeken en -antwoorden voor jouw Gebruikersbeheer API, geschikt voor Swagger-documentatie:
---
### 1. Eindpunt: GET /users/{id}
**Omschrijving:** Haalt details op van een gebruiker op basis van het gebruikers-ID.
#### Voorbeeldverzoek:
```yaml
paths:
/users/{id}:
get:
summary: Haal gebruikersgegevens op
description: |
Dit eindpunt haalt de gegevens op van een gebruiker met het gespecificeerde ID.
parameters:
- name: id
in: path
required: true
description: Het unieke ID van de gebruiker
schema:
type: string
example: "123e4567-e89b-12d3-a456-426614174000"
responses:
'200':
description: Gebruiker gevonden
content:
application/json:
schema:
type: object
properties:
id:
type: string
example: "123e4567-e89b-12d3-a456-426614174000"
naam:
type: string
example: "Jan Jansen"
email:
type: string
example: "jan.jansen@example.com"
geregistreerdOp:
type: string
format: date-time
example: "2023-10-15T10:30:00Z"
'404':
description: Gebruiker niet gevonden
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: "Gebruiker met ID 123e4567-e89b-12d3-a456-426614174000 niet gevonden."
```
#### Voorbeeldantwoord (200):
```json
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"naam": "Jan Jansen",
"email": "jan.jansen@example.com",
"geregistreerdOp": "2023-10-15T10:30:00Z"
}
```
---
### 2. Eindpunt: POST /orders
**Omschrijving:** Plaatst een nieuwe bestelling.
#### Voorbeeldverzoek:
```yaml
paths:
/orders:
post:
summary: Plaats een nieuwe bestelling
description: |
Dit eindpunt wordt gebruikt om een nieuwe bestelling te plaatsen.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
gebruikerId:
type: string
example: "123e4567-e89b-12d3-a456-426614174000"
artikelen:
type: array
items:
type: object
properties:
productId:
type: string
example: "prod-001"
hoeveelheid:
type: integer
example: 2
required:
- gebruikerId
- artikelen
responses:
'201':
description: Bestelling succesvol geplaatst
content:
application/json:
schema:
type: object
properties:
bestelId:
type: string
example: "order-789"
status:
type: string
example: "In behandeling"
geplaatstOp:
type: string
format: date-time
example: "2023-10-15T12:00:00Z"
'400':
description: Ongeldig verzoek
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: "Ongeldige gegevens in het verzoek."
```
#### Voorbeeldantwoord (201):
```json
{
"bestelId": "order-789",
"status": "In behandeling",
"geplaatstOp": "2023-10-15T12:00:00Z"
}
```
---
Met deze gestructureerde voorbeelden kunnen ontwikkelaars eenvoudig begrijpen hoe ze de API kunnen gebruiken en wat ze kunnen verwachten als antwoord. Mocht je meer eindpunten of details nodig hebben, laat het gerust weten!
provider: deepseek
model: deepseek-chat
Zeker, hier zijn realistische voorbeeldverzoeken en -antwoorden voor je Gebruikersbeheer API die je direct in je Swagger documentatie kunt opnemen.
## Eindpunt: `/users/{id}`
### GET /users/{id} - Gebruiker ophalen
**Verzoek:**
```http
GET /users/12345 HTTP/1.1
Host: api.jouwdomein.nl
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
Accept: application/json
```
**Antwoord (200 OK):**
```json
{
"id": 12345,
"voornaam": "Anna",
"achternaam": "Jansen",
"email": "anna.jansen@voorbeeld.nl",
"telefoon": "+31612345678",
"adres": {
"straat": "Hoofdstraat 123",
"postcode": "1234 AB",
"plaats": "Amsterdam",
"land": "Nederland"
},
"rol": "klant",
"actief": true,
"aanmaakdatum": "2023-01-15T10:30:00Z",
"laatsteLogin": "2024-01-20T14:22:10Z"
}
```
**Antwoord (404 Not Found):**
```json
{
"error": {
"code": "GEBRUIKER_NIET_GEVONDEN",
"message": "Gebruiker met ID 99999 niet gevonden",
"details": "Controleer of het gebruikers-ID correct is"
}
}
```
### PUT /users/{id} - Gebruiker bijwerken
**Verzoek:**
```http
PUT /users/12345 HTTP/1.1
Host: api.jouwdomein.nl
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
Content-Type: application/json
{
"voornaam": "Anna",
"achternaam": "Jansen-de Vries",
"telefoon": "+31698765432",
"adres": {
"straat": "Nieuwstraat 456",
"postcode": "5678 CD",
"plaats": "Rotterdam",
"land": "Nederland"
}
}
```
**Antwoord (200 OK):**
```json
{
"id": 12345,
"voornaam": "Anna",
"achternaam": "Jansen-de Vries",
"email": "anna.jansen@voorbeeld.nl",
"telefoon": "+31698765432",
"adres": {
"straat": "Nieuwstraat 456",
"postcode": "5678 CD",
"plaats": "Rotterdam",
"land": "Nederland"
},
"rol": "klant",
"actief": true,
"aanmaakdatum": "2023-01-15T10:30:00Z",
"laatstBijgewerkt": "2024-01-25T09:15:30Z"
}
```
## Eindpunt: `/orders`
### GET /orders - Bestellingen ophalen
**Verzoek met query parameters:**
```http
GET /orders?gebruikerId=12345&status=afgerond&limit=10&offset=0 HTTP/1.1
Host: api.jouwdomein.nl
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
Accept: application/json
```
**Antwoord (200 OK):**
```json
{
"orders": [
{
"orderId": "ORD-2024-001",
"gebruikerId": 12345,
"status": "afgerond",
"totaalBedrag": 149.99,
"valuta": "EUR",
"artikelen": [
{
"artikelId": "ART-001",
"naam": "Wireless Headphones",
"aantal": 1,
"prijsPerStuk": 149.99
}
],
"bezorgadres": {
"straat": "Hoofdstraat 123",
"postcode": "1234 AB",
"plaats": "Amsterdam",
"land": "Nederland"
},
"aanmaakdatum": "2024-01-15T14:30:00Z",
"afgerondDatum": "2024-01-18T10:15:00Z"
}
],
"paginering": {
"totaal": 15,
"limit": 10,
"offset": 0,
"heeftVolgende": true
}
}
```
### POST /orders - Nieuwe bestelling aanmaken
**Verzoek:**
```http
POST /orders HTTP/1.1
Host: api.jouwdomein.nl
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
Content-Type: application/json
{
"gebruikerId": 12345,
"artikelen": [
{
"artikelId": "ART-002",
"aantal": 2
},
{
"artikelId": "ART-005",
"aantal": 1
}
],
"bezorgadres": {
"straat": "Hoofdstraat 123",
"postcode": "1234 AB",
"plaats": "Amsterdam",
"land": "Nederland"
},
"betaalmethode": "creditcard"
}
```
**Antwoord (201 Created):**
```json
{
"orderId": "ORD-2024-002",
"gebruikerId": 12345,
"status": "in_afhandeling",
"totaalBedrag": 89.97,
"valuta": "EUR",
"artikelen": [
{
"artikelId": "ART-002",
"naam": "USB-C Kabel",
"aantal": 2,
"prijsPerStuk": 19.99
},
{
"artikelId": "ART-005",
"naam": "Telefoonhoesje",
"aantal": 1,
"prijsPerStuk": 49.99
}
],
"bezorgadres": {
"straat": "Hoofdstraat 123",
"postcode": "1234 AB",
"plaats": "Amsterdam",
"land": "Nederland"
},
"verzendkosten": 0.00,
"aanmaakdatum": "2024-01-25T11:45:00Z",
"geschatteLeverdatum": "2024-01-30T00:00:00Z"
}
```
**Foutantwoord (400 Bad Request):**
```json
{
"error": {
"code": "ONVOLLEDIGE_BESTELLING",
"message": "Bestelling kon niet worden verwerkt",
"details": [
{
"veld": "artikelen",
"fout": "Minimaal 1 artikel is vereist"
},
{
"veld": "betaalmethode",
"fout": "Betaalmethode is verplicht"
}
]
}
}
```
## Aanbevelingen voor Swagger documentatie:
1. **Voeg response schema's toe** voor alle HTTP statuscodes
2. **Documenteer query parameters** voor GET /orders (gebruikerId, status, limit, offset)
3. **Beschrijf authenticatie** met Bearer tokens
4. **Includeer error handling** voorzieningen
5. **Gebruik Nederlandse veldnamen** voor consistentie
Deze voorbeelden geven ontwikkelaars een duidelijk beeld van hoe ze met je API kunnen werken en welke data ze kunnen verwachten.