Hier is een voorbeeld van een geavanceerd GraphQL-schema voor jouw platform, inclusief custom directives voor veldbeschrijvingen en voorbeelden. Daarnaast licht ik toe hoe deze ontwerpkeuzes de begrijpelijkheid en samenwerking verbeteren. **Voorbeeld schema:** ```graphql # Custom directive voor veldbeschrijvingen en voorbeelden directive @description( text: String! ) on FIELD_DEFINITION | INPUT_FIELD_DEFINITION directive @example( value: String! ) on FIELD_DEFINITION | INPUT_FIELD_DEFINITION type Product { id: ID! @description(text: "Unieke identifier van het product") @example(value: "prod_12345") naam: String! @description(text: "De naam van het product") @example(value: "Bluetooth Koptelefoon") prijs: Float! @description(text: "Prijs van het product in euro") @example(value: "99.99") beschrijving: String @description(text: "Gedetailleerde beschrijving van het product") @example(value: "Draadloze koptelefoon met noise cancelling") voorraad: Int! @description(text: "Aantal beschikbare items in voorraad") @example(value: "50") } type Klant { id: ID! @description(text: "Unieke klant ID") @example(value: "klant_9876") naam: String! @description(text: "Volledige naam van de klant") @example(value: "Jan Jansen") email: String! @description(text: "Emailadres van de klant") @example(value: "jan@example.com") adres: String @description(text: "Factuur- en verzendadres") @example(value: "Straat 1, 1234 AB Stad") telefoon: String @description(text: "Telefoonnummer") @example(value: "+31 6 12345678") } type Bestelling { id: ID! @description(text: "Unieke bestelling ID") @example(value: "bestelling_456") klant: Klant! @description(text: "De klant die de bestelling geplaatst heeft") producten: [Product!]! @description(text: "Lijst van producten in de bestelling") totaalPrijs: Float! @description(text: "Totale prijs van de bestelling") @example(value: "199.98") besteldAt: String! @description(text: "Datum en tijd van bestelling in ISO 8601 formaat") @example(value: "2024-04-27T15:30:00Z") } type Query { producten: [Product!]! @description(text: "Alle beschikbare producten") product(id: ID!): Product @description(text: "Details van een specifiek product") klanten: [Klant!]! @description(text: "Alle klanten") klant(id: ID!): Klant @description(text: "Details van een specifieke klant") bestellingen: [Bestelling!]! @description(text: "Alle bestellingen") bestelling(id: ID!): Bestelling @description(text: "Details van een specifieke bestelling") } ``` **Uitleg over ontwerpkeuzes:** - **Custom directives (@description en @example):** Deze directives zorgen voor gestructureerde metadata bij velden, waardoor tools automatisch uitgebreide documentatie en voorbeelddata kunnen genereren. Dit verbetert de duidelijkheid voor ontwikkelaars en stakeholders. - **Automatische documentatie en visualisaties:** Door deze metadata te standaardiseren, kunnen generatietools, zoals GraphQL Doc generators, automatisch overzichtelijke documentaties en visuele schema-diagrammen produceren. Dit bespaart tijd en vermindert interpretatiefouten. - **Verbeterde begrijpelijkheid:** Door expliciete veldbeschrijvingen en voorbeeldwaarden krijgen nieuwe teamleden en externe ontwikkelaars sneller inzicht in de datamodellen, wat de onboarding versnelt en communicatie verbetert. - **Samenwerking en consistentie:** Het gebruik van gestandaardiseerde directives moedigt teamleden aan om consistente documentatie te schrijven en te onderhouden. Dit voorkomt ambiguïteiten en zorgt voor eenduidigheid in de communicatie. Kortom, door deze ontwerpkeuzes te implementeren, ontstaat een meer transparant, onderhoudbaar en collaboratief ontwikkelproces, ondersteund door automatische documentatie en visuele hulpmiddelen.

Zeker! Ik help je met een geavanceerd GraphQL schema voor een online verkoopplatform. Hieronder vind je een complete implementatie met custom directives en uitgebreide documentatie. ## Schema Definitie met Custom Directives ```graphql # BASIS DIRECTIVES VOOR DOCUMENTATIE directive @description(text: String!) on OBJECT | FIELD_DEFINITION | ARGUMENT_DEFINITION directive @example(value: String!) on FIELD_DEFINITION | ARGUMENT_DEFINITION directive @deprecated(reason: String = "Niet langer ondersteund") on FIELD_DEFINITION # PLATFORM SCHEMA type Query { "Haal producten op met geavanceerde filtering" producten( filter: ProductFilter sortering: Sortering = { veld: NAAM, richting: ASC } ): [Product!]! @description("Query voor het ophalen van producten met filtering en sortering") "Zoek klanten op basis van verschillende criteria" klanten(filter: KlantFilter): [Klant!]! @description("Query voor het zoeken van klanten") "Bekijk bestellingen met paginatie" bestellingen( pagina: Int = 1 perPagina: Int = 20 ): BestellingenResultaat! @description("Opgehaalde bestellingen met paginatie informatie") } type Mutation { "Voeg een nieuw product toe aan de catalogus" maakProduct(input: ProductInput!): Product! @description("Maakt een nieuw product aan in de database") @example(input: "{ naam: \"iPhone 15\", prijs: 999.99 }") "Plaats een nieuwe bestelling" plaatsBestelling(input: BestellingInput!): Bestelling! @description("Verwerkt een nieuwe bestelling van een klant") } # PRODUCT GERELATEERDE TYPES type Product @description("Een product in de online winkel") { id: ID! @description("Unieke identifier voor het product") naam: String! @description("Naam van het product") @example(value: "iPhone 15 Pro") beschrijving: String @description("Gedetailleerde productbeschrijving") prijs: Float! @description("Prijs in EUR") @example(value: "999.99") voorraad: Int! @description("Aantal beschikbare items") @example(value: "50") categorie: Categorie! @description("Productcategorie") createdAt: String! @description("Aanmaakdatum") updatedAt: String! @description("Laatste wijzigingsdatum") } input ProductInput @description("Input voor het aanmaken/bijwerken van producten") { naam: String! @example(value: "Samsung Galaxy S24") beschrijving: String @example(value: "Nieuwste Samsung smartphone") prijs: Float! @example(value: "899.99") voorraad: Int! @example(value: "100") categorieId: ID! @example(value: "cat_123") } input ProductFilter @description("Filter opties voor producten") { zoekterm: String @description("Zoek in naam en beschrijving") @example(value: "phone") minPrijs: Float @description("Minimum prijs") @example(value: "100.00") maxPrijs: Float @description("Maximum prijs") @example(value: "1000.00") categorie: ID @description("Filter op categorie ID") opVoorraad: Boolean @description("Alleen producten op voorraad") } # KLANT GERELATEERDE TYPES type Klant @description("Een klant van het platform") { id: ID! @description("Unieke klant identifier") email: String! @description("E-mailadres van de klant") @example(value: "klant@voorbeeld.nl") voornaam: String! @description("Voornaam van de klant") @example(value: "Jan") achternaam: String! @description("Achternaam van de klant") @example(value: "Jansen") telefoon: String @description("Telefoonnummer") @example(value: "+31612345678") adres: Adres @description("Standaard adres van de klant") bestellingen: [Bestelling!]! @description("Geschiedenis van bestellingen") } input KlantFilter @description("Filter opties voor klanten") { email: String @example(value: "jan@") naam: String @description("Zoek in voornaam en achternaam") @example(value: "Jansen") } # BESTELLING GERELATEERDE TYPES type Bestelling @description("Een bestelling geplaatst door een klant") { id: ID! @description("Unieke bestelling identifier") klant: Klant! @description("Klant die de bestelling heeft geplaatst") producten: [Bestelregel!]! @description("Producten in de bestelling") totaalBedrag: Float! @description("Totaalbedrag van de bestelling") status: BestelStatus! @description("Huidige status van de bestelling") createdAt: String! @description("Datum van plaatsen bestelling") updatedAt: String! @description("Laatste status wijziging") } type Bestelregel @description("Een regel in een bestelling") { product: Product! @description("Het bestelde product") aantal: Int! @description("Aantal bestelde items") @example(value: "2") prijs: Float! @description("Prijs per stuk op moment van bestellen") } input BestellingInput @description("Input voor het plaatsen van een bestelling") { klantId: ID! @example(value: "klant_123") producten: [BestelregelInput!]! @description("Producten om te bestellen") } input BestelregelInput @description("Input voor een bestelregel") { productId: ID! @example(value: "prod_456") aantal: Int! @example(value: "1") } # OVERIGE TYPES type Categorie @description("Productcategorie") { id: ID! naam: String! @example(value: "Elektronica") omschrijving: String } type Adres @description("Adres van een klant") { straat: String! @example(value: "Kerkstraat 123") postcode: String! @example(value: "1234 AB") plaats: String! @example(value: "Amsterdam") land: String! @example(value: "Nederland") } type BestellingenResultaat @description("Gepagineerd resultaat voor bestellingen") { bestellingen: [Bestelling!]! totaal: Int! @description("Totaal aantal bestellingen") pagina: Int! @description("Huidige pagina") perPagina: Int! @description("Aantal items per pagina") } enum BestelStatus @description("Status van een bestelling") { WACHTEND @description("Bestelling is geplaatst maar nog niet verwerkt") BEVESTIGD @description("Bestelling is bevestigd") VERZONDEN @description("Bestelling is verzonden") AFGELEVERD @description("Bestelling is afgeleverd") GEANNULEERD @description("Bestelling is geannuleerd") } enum SorteringRichting { ASC DESC } input Sortering { veld: String! richting: SorteringRichting! } ``` ## Implementatie van Documentatie Generatie ```javascript // Documentatie generator voor GraphQL schema const generateSchemaDocumentation = (schema) => { const types = schema.getTypeMap(); return Object.values(types) .filter(type => !type.name.startsWith('__')) .map(type => ({ name: type.name, description: type.description || 'Geen beschrijving beschikbaar', kind: type.constructor.name, fields: type.getFields ? Object.values(type.getFields()).map(field => ({ name: field.name, description: field.description, type: field.type.toString(), args: field.args.map(arg => ({ name: arg.name, description: arg.description, type: arg.type.toString() })) })) : [] })); }; ``` ## Voordelen voor Teams ### 1. **Zelf-documenterend Schema** - **Directives zoals `@description` en `@example`** zorgen voor consistente documentatie - **Automatische type safety** voorkomt miscommunicatie tussen frontend en backend - **Live voorbeelden** helpen ontwikkelaars snel te begrijpen hoe queries te gebruiken ### 2. **Verbeterde Samenwerking** ```graphql # VOORBEELD: Duidelijke intentie door beschrijvingen type Bestelling { status: BestelStatus! @description("Huidige status in het bestelproces") @example(value: "VERZONDEN") } ``` ### 3. **Visualisatie Tools Integratie** ```javascript // Integratie met GraphQL Voyager voor schema visualisatie const voyagerMiddleware = require('graphql-voyager/middleware'); app.use('/voyager', voyagerMiddleware({ endpointUrl: '/graphql', headers: { 'Authorization': 'Bearer {token}' } })); ``` ### 4. **Type-safe Development** ```typescript // Automatisch gegenereerde TypeScript types interface Product { id: string; naam: string; prijs: number; voorraad: number; // ... alle velden zijn bekend door het schema } ``` ## Best Practices voor Team Gebruik 1. **Standaardiseer Directive Gebruik** - Elke type en veld moet een `@description` hebben - Complexe velden moeten `@example` bevatten - Gebruik `@deprecated` voor achterwaartse compatibiliteit 2. **Schema First Development** - Definieer eerst het schema voordat je implementeert - Review schema wijzigingen in teamverband - Gebruik tools zoals GraphQL Code Generator 3. **Documentatie als Levend Document** - Schema documentatie wordt automatisch bijgewerkt - Wijzigingen zijn direct zichtbaar voor het hele team - Vermindert de noodzaak voor aparte API documentatie Dit ontwerp zorgt voor een **schaalbaar, goed gedocumenteerd systeem** dat de productiviteit van ontwikkelteams aanzienlijk verbetert en miscommunicatie minimaliseert.