OpenAPI fehlerhafte JSON Datei
-
Hallo liebe ChurchTools Entwickler!
Ich wollte mich wieder näher mit der neuen API auseinandersetzen und dafür auch die schicke OpenAPI Dokumentation nutzen. Mein Plan war, mit Hilfe von jane einen API-Client zu generieren - das sollte ja mit der vorhandenen openapi.json sinnvoll funktionieren. Leider klappt das gar nicht, weil die openapi.json viel zu viele Fehler hat. Einige können zwar schnell behoben werden, trotzdem ist es praktisch unmöglich einen sinnvollen Client zu generieren (als Dokumentation für die manuelle Umsetzung eignet es sich natürlich trotzdem).
Ich bin kein Experte für OpenAPI, aber habe recht schnell festgestellt, dass das Problem wohl eindeutig bei ChurchTools liegt. Diverse OpenAPI-Validatoren zeigen Unmengen an Fehlern im Dokument an (z.B. vacuum). Die meisten Stichproben sind für mich eindeutig nachvollziehbar:
- operationIds sind nicht eindeutig für:
getPersonRelationships - type als array statt string definiert, zB:
components.schemas.GroupMemberHistoryEntry.properties.current.properties.fields.additionalProperties.type - Duplikate/Redundanzen bei Parametern (common parameters werden in operation parameters wiederholt), z.B. bei
paths./groups/{groupId}/chat - Schemas werden definiert, aber an keiner Stelle referenziert (
$refkommt nirgends vor) - [edit] Leere Parameter-Namen in Response-Schemata, z.B.
paths./calendars{calendarId}/appointments.get.responses.200.content.application/json.schema.properties
Da ich auch ein paar ältere Beiträge zur fehlerhaften openapi.json gefunden habe (2019, 2021) bleibt die Frage, ob und wann wir mit einer validen OpenAPI Dokumentation rechnen können? Klar, falsch dokumentierte Parameter oder Rückgabewerte wirds immer irgendwo geben, aber die openapi.json sollte wenigstens der OpenAPI Spezifikation entsprechen ...
- operationIds sind nicht eindeutig für: