Automatisch documentatie testen met PlantUML en OpenAPI

Softwaredocumentatie is een onmisbaar onderdeel van softwareontwikkeling. Het laat ontwikkelaars uit verschillende teams toe om ten volle gebruik te maken van elkaars services, maar helaas is die documentatie vaak moeilijk gesynchroniseerd te houden met de code. Onze medewerker Mark Dechamps en zijn team zochten en vonden een manier om automatisch te controleren of onze interne documentatie nog up-to-date is.

Mark: Bij onze klanten gebruiken we PlantUML om diagrammen te tekenen voor onze interne documentatie op Confluence. Die documentatie beschrijft de API’s van onze services aan de hand van flowcharts. Omdat deze documentatie erg handig is voor de communicatie tussen teams, is het van cruciaal belang dat die diagrammen alle details correct aanduiden. Als er een parameter of een ander onderdeel gewijzigd wordt, moet dit zo snel mogelijk zichtbaar zijn in de documentatie.

Onze oplossing bestaat uit een soort unit test die controleert of de documentatie nog klopt. Dat doen we door een PlantUML bestand bij onze code te zetten, en tijdens de build een test te draaien die de OpenAPI opvraagt en vergelijkt met het PlantUML diagram. Als de bestanden niet overeenkomen, faalt de test en krijgen we een foutmelding te zien.

We hebben het project in TypeScript geschreven op Node.js. Het maakt gebruik van Purify, een library voor functioneel programmeren met TypeScript. Het was hard werken, maar op het einde van de Innovation Day hadden we al een eerste werkende versie die ontbrekende nodes in de diagrammen kon detecteren!

Een CLI voor React en React Native

Mocht de term CLI je niet bekend in de oren klinken, dan zal je het fenomeen vast wel herkennen uit scènes in films of televisieseries waar hacken aan te pas komt. Een CLI of Command Line Interface is een doorgaans zwart scherm waarop gebruikers commando’s kunnen ingeven om een programma of besturingssysteem aan te sturen. Onze collega Jos De Berdt geeft wat meer uitleg bij de nieuwe CLI die zijn team ontwikkelde voor React en React Native.

Jos: Op televisie zien ze er vooral indrukwekkend en technisch ingewikkeld uit, maar CLI’s hebben in de realiteit zeker ook hun nut. Het zorgt ervoor dat we als ontwikkelaars een project makkelijker kunnen beheren en documenteren. Dat zorgt dan weer voor een snellere aflevering (van de code, niet van een televisieserie), meer consistentie in onze code, en een accuratere documentatie.

Ook wij kozen voor Node.js om onze CLI te maken. De CLI laat ons toe om snel en gemakkelijk bestanden met componenten, states en andere functies in React en React Native aan te maken. Bovendien installeert het de meest gebruikte modules en helpt het ons bij het schrijven van documentatie. Dankzij een verbinding van de CLI met het project zelf in plaats van met een code-editor kunnen we ook al onze favoriete shortcuts (sneltoetsen) overal blijven gebruiken.

Een van onze pilaren binnen Sweet Mustard is een inspirerende community opbouwen, en daar draagt dit project ten volle aan bij. We zullen de code voor deze CLI dan ook via de node packaging manager (NPM) beschikbaar maken voor de volledige Node.js community.

Automatisatie van designsystemen

Bij het ontwikkelen en onderhouden van een designsysteem komt er vaak heel wat manueel werk kijken, zoals voorbeelden up-to-date houden en design tokens aligneren met zowel design als code. Als niet alle wijzigingen in design of code doorgevoerd worden in het systeem, bestaat het gevaar dat de kloof tussen design en ontwikkeling groter wordt.

Een designsysteem is echter net bedoeld om die partijen dichter bij elkaar te brengen, dus het belang van synchronisatie kan amper onderschat worden. Bij Sweet Mustard was dit niet anders, dus hebben enkele van onze ontwikkelaars besloten om de cirkel tussen design, documentatie en ontwikkeling rond te maken en enkele zaken te automatiseren. Onze collega Ibe Vanmeenen legt uit hoe ze dat precies gedaan hebben.

Ibe: Onze vroegere werkwijze was om een afbeelding te exporteren van een component uit Figma, het programma dat we voor onze designs gebruiken. Die component plaatsten we vervolgens manueel als een afbeelding in ons designsysteem. We moesten deze documentatie bovendien ook manueel bijwerken als er aanpassingen werden doorgevoerd aan het stuk implementatie van de component in code.

Onze nieuwe setup maakt gebruik van het Zeroheight programma en kan verbinden met zowel Storybook (code) als Figma (design). Manuele aanpassingen zijn intussen verleden tijd, want alle wijzigingen worden automatisch gesynchroniseerd. Er komt dus veel minder onderhoudswerk en manuele documentatie bij kijken. Zo helpt onze oplossing ons om het ontwikkelen en onderhouden van designsystemen pragmatisch aan te pakken, zonder de kosten die hier doorgaans mee gepaard gaan.

Ook dit jaar waren er weer heel wat interessante technische ontwikkelingen, door en voor onze medewerkers. Wil je Sweet Mustard graag mee laten groeien, werken met de nieuwste technologieën, en je collega’s zo elke dag helpen? Neem dan zeker contact met ons op, want we zijn altijd op zoek naar nieuwe enthousiastelingen!