In OAS zijn info.description en info.summary (vanaf OAS 3.1) optioneel. Ik zou beide velden graag willen verplichten of tenminste sterk willen aanbevelen met richtlijnen over wat waar op te nemen, zodat gebruikers (inclusief LLM's overigens) weten waar de API over gaat en waar je deze voor kunt gebruiken.
Bijvangst: in OAS 3.0 bestaat er alleen een optionele info.description die we bij het API-register gebruiken om de beschrijving op de detailpagina én de overzichtspagina te vullen. Op de overzichtspagina is dit te lang, dus willen we dit truncaten, maar vanuit a11y mag dit niet met CSS opgelost worden. Dit betekent dat we de info.description moeten truncaten, nadat het bovendien ontdaan is van eventuele markdown. Dit terwijl er vanaf OAS 3.1 een info.summary property is, die (in tegenstelling tot info.description) géén markdown mag bevatten en derhalve precies voor deze usecase bedoeld is.
In OAS zijn
info.descriptioneninfo.summary(vanaf OAS 3.1) optioneel. Ik zou beide velden graag willen verplichten of tenminste sterk willen aanbevelen met richtlijnen over wat waar op te nemen, zodat gebruikers (inclusief LLM's overigens) weten waar de API over gaat en waar je deze voor kunt gebruiken.Bijvangst: in OAS 3.0 bestaat er alleen een optionele
info.descriptiondie we bij het API-register gebruiken om de beschrijving op de detailpagina én de overzichtspagina te vullen. Op de overzichtspagina is dit te lang, dus willen we dit truncaten, maar vanuit a11y mag dit niet met CSS opgelost worden. Dit betekent dat we deinfo.descriptionmoeten truncaten, nadat het bovendien ontdaan is van eventuele markdown. Dit terwijl er vanaf OAS 3.1 eeninfo.summaryproperty is, die (in tegenstelling totinfo.description) géén markdown mag bevatten en derhalve precies voor deze usecase bedoeld is.