Beheer: specificeer scope (formats veld) van de ruleset

[erwinkramer]

De scope van de ruleset is grotendeels het valideren van OpenAPI 3.x specs. Daarom zou het formats veld benut moeten kunnen worden. Nu geldt de ruleset ook voor elk ander mogelijk format buiten OpenAPI, zoals AsyncAPI en Arazzo, wat niet de bedoeling zou mogen zijn.

Ik liep hier zelf tegenaan, omdat je bijvoorbeeld in de VS Code extensie van Spectral maar 1 rulesetfile kan definiëren voor een hele repo, terwijl er in mijn geval meerdere type specs worden gevalideerd, zoals Arazzo en OpenAPI 3.x. Het zou dan ook mogelijk moeten zijn om voor 1 ruleset meerdere formats te kunnen bedienen, zonder elkaar in de weg te zitten.

Deze PR voegt oas3 toe als format. Voor nlgov:openapi-root-exists heb ik het format oas2 toegevoegd, om toch een validatiefout te krijgen als je op openapi 2.x zit. Omdat v2 eigenlijk wordt gedefinieerd via { "swagger": "2.0", [...] }, heeft het geen zin om voor deze rule op oas3 te checken of de openapi root bestaat, aangezien oas3 als formats al impliciet betekend dat je dit correct hebt genoteerd, alvorens een rule voor dit format wordt geactiveerd.

Dit zorgt wel voor falende testcases...:

Error:  1:1    error  nlgov:openapi-root-exists  The root of the document must contain the `openapi` property.
Warning:  1:1  warning  unrecognized-format        The provided document does not match any of the registered formats [OpenAPI 2.0 (Swagger), OpenAPI 3.x, OpenAPI 3.0.x, OpenAPI 3.1.x]

...maargoed, ik denk niet dat deze insteek voor de testcases nuttig is voor de API Design Rules. Op moment dat een willekeurig json/yaml document herkend wordt als een OpenAPI/Swagger document (via swagger of openapi element), pas dan zou de API Design Rules er op losgelaten mogen worden, lijkt mij. De expected output van deze testcase heb ik daarom ook aangepast.

De links check gaat trouwens nog fout, ik denk dat dit niet gerelateerd is aan mijn PR.

[TimvdLippe]

Top, dit lijkt mij een goede fix! Zou je ook een testcase willen toevoegen met een minimaal Arazzo spec (of andere file format die je gebruikt) en dan met de expected output dat er geen errors zijn? Dan hebben we zo de regressie test dat je niet nog een keer in die situatie komt.

Link checker is idd ongerelateerd. Is helaas het gevolg van omgaan met ongebreideld AI crawlers waardoor onze link checker ook soms word gezien als crawler 😢

[erwinkramer]

@TimvdLippe ik heb een Arazzo spec met case toegevoegd. Omdat het lintingscript van een openapi.json bestand uitging, heb ik dat veranderd naar een manier waarbij simpelweg het eerste *.json bestand gepakt wordt. Trouwens, Arazzo 1.1.0 bestaat, maar Spectral snapt dat nog niet, dus de versie daarvoor (1.0.1) gebruikt.

Ook heb ik een swagger.json case toegevoegd.

Tenslotte is openapi-versie-missing hernoemd naar unrecognized-format-openapi, aangezien het nu meer een check is geworden op herkenning van OpenAPI (zoals bij de Arazzo case), i.p.v. validatie van een veld in een vermoedelijk OpenAPI document.

[TimvdLippe]

1 kleine nit, de rest ziet er goed uit. Thanks voor het fixen!