Maak een OpenAPI-specificatie voor API-versiebeheer en compatibiliteit

description

Met deze prompt kun je een OpenAPI-specificatie maken die expliciet versiebeheer en compatibiliteitsregels beschrijft. Dit voorkomt integratieproblemen bij API-updates, zorgt voor duidelijke communicatie naar ontwikkelaars en verbetert de onderhoudbaarheid van je API-documentatie. Het is een unieke aanpak die helpt om toekomstige wijzigingen zonder verwarring te beheren.

prompt

Help me een OpenAPI-specificatie te ontwerpen die duidelijk versiebeheer en compatibiliteitsregels voor mijn API beschrijft. API-naam: <voer de naam van mijn API in> Huidige API-versie: <voer de huidige API-versie in> Gewenste versiebeheerstrategie (bijv. semver, datumgebaseerd): <beschrijf de versiebeheerstrategie> Compatibiliteitsregels (bijv. a ...

try_prompt

De naam van je API

De huidige versie van je API

De versiebeheerstrategie die je wilt toepassen, bijvoorbeeld semver of datumgebaseerd

Regels voor compatibiliteit, zoals achterwaartse compatibiliteit of deprecated endpoints

De belangrijkste API endpoints en HTTP-methoden die je wilt documenteren

De authenticatiemethode die je API gebruikt

generate_helper

disclaimerOnPageApi

ai_answers

provider: openai

model: gpt-4.1-nano

openapi: 3.0.3 info: title: E-commerce API version: 1.0.0 description: > Deze API volgt semver (Semantic Versioning) voor versiebeheer. - Major-versies breken compatibiliteit - Minor-versies voegen functionaliteit toe zonder compatibiliteit te breken - Patch-versies bevatten bugfixes en kleine verbeteringen Let op: deprecated endpoints worden gemarkeerd en blijven ondersteund totdat ze worden verwijderd in een toekomstige versie. contact: name: Support email: support@ecommerce.com servers: - url: https://api.ecommerce.com/v1 description: Productieomgeving - versie 1.x.x components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-KEY security: - ApiKeyAuth: [] paths: /users: get: summary: "Lijst van gebruikers" description: > Hiermee haalt u een lijst van gebruikers op. **Let op:** Dit endpoint is actief en wordt ondersteund. Toekomstige deprecatie wordt aangekondigd via documentatie. responses: '200': description: "Lijst van gebruikers" content: application/json: schema: type: array items: $ref: '#/components/schemas/User' post: summary: "Maak een nieuwe gebruiker" description: > Hiermee maakt u een nieuwe gebruiker aan. **Let op:** Dit endpoint wordt ondersteund en kan worden aangepast of gedepricated in toekomstige versies. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/NewUser' responses: '201': description: "Gebruiker aangemaakt" content: application/json: schema: $ref: '#/components/schemas/User' # Deprecated endpoint voorbeeld /old-users: get: deprecated: true summary: "Oud gebruikerslijst (deprecated)" description: > Dit endpoint is gedepricated en wordt mogelijk in toekomstige versies verwijderd. responses: '200': description: "Oud gebruikerslijst" content: application/json: schema: type: array items: $ref: '#/components/schemas/User' /orders: get: summary: "Lijst van bestellingen" description: > Haalt een lijst van bestellingen op. **Let op:** Dit endpoint wordt ondersteund en blijft compatibel in toekomstige versies. responses: '200': description: "Lijst van bestellingen" content: application/json: schema: type: array items: $ref: '#/components/schemas/Order' components: schemas: User: type: object properties: id: type: string description: "Unieke identifier van de gebruiker" name: type: string email: type: string required: - id - name - email NewUser: type: object properties: name: type: string email: type: string required: - name - email Order: type: object properties: orderId: type: string userId: type: string amount: type: number format: float required: - orderId - userId - amount # Notities: # - De API volgt semver: wijzigingen worden gespecificeerd in nieuwe versies. # - Deprecated endpoints worden gemarkeerd en blijven in de documentatie, met vermelding dat ze mogelijk worden verwijderd. # - Authenticatie gebeurt via API Key in header X-API-KEY. # - Versie 1.0.0 is de huidige stabiele release; toekomstige versies moeten compatibel blijven tenzij een breaking change wordt geïntroduceerd.

provider: deepseek

model: deepseek-chat

Zeker, hier is een OpenAPI 3.0-specificatie in YAML voor jouw E-commerce API met duidelijk versiebeheer en compatibiliteitsregels: ```yaml openapi: 3.0.0 info: title: E-commerce API description: | API voor e-commerce functionaliteiten. **Versiebeheer**: Deze API volgt Semantic Versioning (SemVer). **Compatibiliteit**: We garanderen achterwaartse compatibiliteit voor minor en patch versies. Endpoints die worden afgeschaft worden gemarkeerd als deprecated en blijven minimaal één major versie beschikbaar. version: 1.0.0 contact: name: API Ondersteuning email: api-support@example.com license: name: Proprietary url: https://example.com/license servers: - url: https://api.example.com/v1 description: Productie server - versie 1.0.0 tags: - name: Gebruikers description: Beheer van gebruikersaccounts - name: Bestellingen description: Beheer van bestellingen paths: /users: get: tags: - Gebruikers summary: Haal gebruikerslijst op description: Geeft een lijst van alle gebruikers terug operationId: getUsers security: - ApiKeyAuth: [] parameters: - name: limit in: query description: Maximum aantal gebruikers om terug te geven required: false schema: type: integer default: 100 - name: offset in: query description: Aantal gebruikers om over te slaan required: false schema: type: integer default: 0 responses: '200': description: Succesvolle response content: application/json: schema: type: array items: $ref: '#/components/schemas/User' '401': $ref: '#/components/responses/UnauthorizedError' '500': $ref: '#/components/responses/ServerError' post: tags: - Gebruikers summary: Maak een nieuwe gebruiker aan description: Creëert een nieuwe gebruiker in het systeem operationId: createUser security: - ApiKeyAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UserCreate' responses: '201': description: Gebruiker succesvol aangemaakt content: application/json: schema: $ref: '#/components/schemas/User' '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '500': $ref: '#/components/responses/ServerError' /orders: get: tags: - Bestellingen summary: Haal bestellingen op description: Geeft een lijst van bestellingen terug (mogelijk deprecated in toekomstige versies) operationId: getOrders deprecated: false # Kan op true worden gezet bij deprecation security: - ApiKeyAuth: [] parameters: - name: user_id in: query description: Filter bestellingen op gebruiker ID required: false schema: type: string - name: status in: query description: Filter bestellingen op status required: false schema: type: string enum: [pending, processing, completed, cancelled] responses: '200': description: Succesvolle response content: application/json: schema: type: array items: $ref: '#/components/schemas/Order' '401': $ref: '#/components/responses/UnauthorizedError' '500': $ref: '#/components/responses/ServerError' components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: Jouw API key voor authenticatie schemas: User: type: object properties: id: type: string format: uuid description: Unieke identifier van de gebruiker email: type: string format: email description: E-mailadres van de gebruiker name: type: string description: Volledige naam van de gebruiker created_at: type: string format: date-time description: Aanmaakdatum van de gebruiker required: - id - email - name - created_at UserCreate: type: object properties: email: type: string format: email description: E-mailadres van de gebruiker name: type: string description: Volledige naam van de gebruiker password: type: string format: password description: Wachtwoord van de gebruiker required: - email - name - password Order: type: object properties: id: type: string format: uuid description: Unieke identifier van de bestelling user_id: type: string format: uuid description: ID van de gebruiker total_amount: type: number format: float description: Totaalbedrag van de bestelling status: type: string enum: [pending, processing, completed, cancelled] description: Status van de bestelling created_at: type: string format: date-time description: Aanmaakdatum van de bestelling required: - id - user_id - total_amount - status - created_at responses: UnauthorizedError: description: Ongeautoriseerde toegang - API key ontbreekt of is ongeldig BadRequestError: description: Ongeldig verzoek - ontbrekende of incorrecte parameters ServerError: description: Interne serverfout - probeer het later opnieuw externalDocs: description: API Documentatie en Versiebeleid url: https://developer.example.com/api-docs ``` **Belangrijke versiebeheer en compatibiliteitskenmerken:** 1. **Semantic Versioning**: Duidelijk aangegeven in de beschrijving 2. **Versie in URL**: `/v1` in server URL voor versiescheiding 3. **Deprecation marking**: `deprecated: true/false` voor endpoints 4. **Achterwaartse compatibiliteit**: Beschreven in API beschrijving 5. **Version header**: Optioneel toe te voegen voor versie-negotiation 6. **Change management**: Documentatie link voor versiebeleid Je kunt de `deprecated: true` vlag gebruiken wanneer je endpoints wilt afschaffen, en ze minimaal één major versie beschikbaar houden zoals aangegeven in je compatibiliteitsregels.