Zeker! Hieronder vind je een gestructureerde voorbeeld van een Swagger (OpenAPI) specificatie voor jouw Gebruikersbeheer API. Deze documentatie is ontworpen om zowel technisch als niet-technisch gebruikers te helpen, met duidelijke beschrijvingen, voorbeeldverzoeken en -antwoorden, en ondersteuning voor OAuth 2.0 authenticatie. --- ```yaml openapi: 3.0.3 info: title: Gebruikersbeheer API description: > Dit is de officiële API voor het beheren van gebruikers binnen uw systeem. Met deze API kunt u gebruikers opvragen, toevoegen en details bekijken. De API ondersteunt OAuth 2.0 authenticatie, JSON-responses en paginering voor overzichtelijke gegevens. version: "1.0.0" contact: name: Ondersteuning email: support@voorbeeld.com servers: - url: https://api.voorbeeld.com/v1 description: Productie server components: securitySchemes: OAuth2: type: oauth2 flows: authorizationCode: authorizationUrl: https://auth.voorbeeld.com/oauth/authorize tokenUrl: https://auth.voorbeeld.com/oauth/token scopes: read:users: "Leesrechten voor gebruikers" write:users: "Schrijfrechten voor gebruikers" schemas: User: type: object properties: id: type: string description: Unieke identificatie van de gebruiker name: type: string description: Naam van de gebruiker email: type: string format: email description: E-mailadres van de gebruiker createdAt: type: string format: date-time description: Aanmaakdatum van de gebruiker UserList: type: object properties: total: type: integer description: Totaal aantal gebruikers page: type: integer perPage: type: integer users: type: array items: $ref: '#/components/schemas/User' security: - OAuth2: [read:users, write:users] tags: - name: Gebruikers description: Beheer van gebruikersgegevens paths: /users: get: tags: - Gebruikers summary: "Lijst van gebruikers opvragen" description: > Haal een lijst op van alle gebruikers. Ondersteunt paginering voor grote datasets. security: - OAuth2: [read:users] parameters: page: name: page in: query description: "Pagina nummer (standaard 1)" required: false schema: type: integer default: 1 perPage: name: perPage in: query description: "Aantal gebruikers per pagina (standaard 10)" required: false schema: type: integer default: 10 responses: 200: description: > Een lijst met gebruikers, inclusief paginering details. content: application/json: schema: $ref: '#/components/schemas/UserList' examples: example1: summary: Voorbeeld respons value: total: 50 page: 1 perPage: 10 users: [ /* array van gebruikers */ ] post: tags: - Gebruikers summary: "Nieuwe gebruiker aanmaken" description: > Voer de gegevens van een nieuwe gebruiker in om deze toe te voegen aan het systeem. security: - OAuth2: [write:users] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/User' examples: example1: summary: Voorbeeld nieuwe gebruiker value: name: Jan Jansen email: jan.jansen@voorbeeld.com responses: 201: description: "Gebruiker succesvol aangemaakt" content: application/json: schema: $ref: '#/components/schemas/User' 400: description: "Ongeldige invoergegevens" /users/{id}: get: tags: - Gebruikers summary: "Details van een specifieke gebruiker opvragen" description: > Haal gedetailleerde informatie op van een gebruiker via hun unieke ID. security: - OAuth2: [read:users] parameters: id: name: id in: path description: "Unieke identificatie van de gebruiker" required: true schema: type: string responses: 200: description: "Details van de gebruiker" content: application/json: schema: $ref: '#/components/schemas/User' 404: description: "Gebruiker niet gevonden" --- # Samenvatting Deze API biedt eenvoudige en gestructureerde toegang tot gebruikersgegevens met beveiliging via OAuth 2.0. De documentatie bevat duidelijke beschrijvingen en voorbeelden voor gebruiksvriendelijkheid, zowel voor ontwikkelaars als niet-technische stakeholders. --- Wil je dat ik deze specificatie verder uitbreid of in een ander formaat lever?

Zeker! Hier is een complete Swagger/OpenAPI-documentatie voor je Gebruikersbeheer API in YAML-formaat: ```yaml openapi: 3.0.0 info: title: Gebruikersbeheer API description: | ## Overzicht Deze API biedt een compleet beheersysteem voor gebruikersgegevens. Met deze service kunnen gebruikers worden opgehaald, aangemaakt en beheerd. ## Doelgroep - **Ontwikkelaars**: Technische integratie met de gebruikersbeheer-functionaliteiten - **Beheerders**: Beheer van gebruikersaccounts en toegangsrechten ## Belangrijke Kenmerken - ✅ OAuth 2.0 Authenticatie - ✅ JSON-formaat voor alle requests en responses - ✅ Paginering voor grote datasets - ✅ Gedetailleerde foutmeldingen version: 1.0.0 contact: name: API Ondersteuning email: support@gebruikersbeheer.nl servers: - url: https://api.gebruikersbeheer.nl/v1 description: Productie server - url: https://sandbox.api.gebruikersbeheer.nl/v1 description: Testomgeving tags: - name: Gebruikers description: Operaties voor gebruikersbeheer paths: /users: get: tags: - Gebruikers summary: Lijst van gebruikers ophalen description: | Haalt een gepagineerde lijst op van alle geregistreerde gebruikers. Geschikt voor het tonen van gebruikers in beheerinterfaces. **Opmerking voor niet-technische gebruikers**: Deze functie toont alle gebruikers in het systeem, met opties voor filteren en sorteren. security: - OAuth2: [users.read] parameters: - name: page in: query description: Paginanummer (standaard 1) required: false schema: type: integer minimum: 1 default: 1 - name: limit in: query description: Aantal items per pagina (standaard 10, max 100) required: false schema: type: integer minimum: 1 maximum: 100 default: 10 responses: '200': description: Succesvolle response met lijst van gebruikers content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/User' pagination: $ref: '#/components/schemas/Pagination' '401': description: Niet geautoriseerd '500': description: Server error post: tags: - Gebruikers summary: Nieuwe gebruiker aanmaken description: | Maakt een nieuwe gebruiker aan in het systeem. **Opmerking voor niet-technische gebruikers**: Vul de verplichte velden in om een nieuwe gebruiker te registreren. security: - OAuth2: [users.write] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UserInput' responses: '201': description: Gebruiker succesvol aangemaakt content: application/json: schema: $ref: '#/components/schemas/User' '400': description: Ongeldige invoer '401': description: Niet geautoriseerd '409': description: Gebruiker bestaat al /users/{id}: get: tags: - Gebruikers summary: Specifieke gebruiker ophalen description: | Haalt gedetailleerde informatie op over een specifieke gebruiker op basis van ID. security: - OAuth2: [users.read] parameters: - name: id in: path required: true description: Unieke identifier van de gebruiker schema: type: string format: uuid responses: '200': description: Gebruiker details content: application/json: schema: $ref: '#/components/schemas/User' '401': description: Niet geautoriseerd '404': description: Gebruiker niet gevonden components: schemas: User: type: object properties: id: type: string format: uuid description: Unieke identifier van de gebruiker naam: type: string description: Volledige naam van de gebruiker email: type: string format: email description: E-mailadres van de gebruiker telefoon: type: string description: Telefoonnummer aangemaaktOp: type: string format: date-time description: Aanmaakdatum en tijd bijgewerktOp: type: string format: date-time description: Laatste update datum en tijd UserInput: type: object required: - naam - email properties: naam: type: string example: "Jan Jansen" email: type: string format: email example: "jan.jansen@voorbeeld.nl" telefoon: type: string example: "+31612345678" Pagination: type: object properties: pagina: type: integer description: Huidige paginanummer perPagina: type: integer description: Aantal items per pagina totaal: type: integer description: Totaal aantal items totalePaginas: type: integer description: Totaal aantal pagina's securitySchemes: OAuth2: type: oauth2 flows: authorizationCode: authorizationUrl: https://auth.gebruikersbeheer.nl/authorize tokenUrl: https://auth.gebruikersbeheer.nl/token scopes: users.read: Lees toegang tot gebruikers users.write: Schrijf toegang tot gebruikers responses: UnauthorizedError: description: Toegang geweigerd - authenticatie vereist NotFoundError: description: De gevraagde resource bestaat niet ``` ## Gebruiksinstructies: 1. **Sla deze code op** als `openapi.yaml` of `openapi.json` 2. **Importeer het bestand** in Swagger UI, Redoc, of een andere OpenAPI-tool 3. **Pas de server URLs aan** naar jouw werkelijke endpoints 4. **Test de authenticatie** door je OAuth 2.0 configuratie te verifiëren ## Extra tips voor gebruiksvriendelijkheid: - **Voor niet-technische gebruikers**: De beschrijvingen zijn in begrijpelijke taal geschreven - **Voor ontwikkelaars**: Alle technische details zijn aanwezig met duidelijke voorbeelden - **Interactive testing**: Gebruikers kunnen direct requests testen via de Swagger UI interface - **Error handling**: Duidelijke foutmeldingen voor verschillende scenario's Deze documentatie biedt een complete en professionele weergave van je API die zowel technische als niet-technische gebruikers zal aanspreken!