api-oas-checker

api-oas-checker copied to clipboard

I expect

• A rule enforcing pagination on GET requests

• The rule should comply with:

  • https://italia.github.io/lg-modellointeroperabilita-docs/doc/04_Raccomandazioni%20di%20implementazione/05_raccomandazioni-tecniche-per-rest/02_progettazione-e-naming.html?highlight=limit#rac-rest-name-004-le-collezioni-di-risorse-possono-usare-nomi-al-plurale
  • https://italia.github.io/lg-modellointeroperabilita-docs/doc/04_Raccomandazioni%20di%20implementazione/05_raccomandazioni-tecniche-per-rest/02_progettazione-e-naming.html?highlight=limit

La paginazione DEVE essere implementata tramite i parametri: cursor, limit, offset, sort

La ricerca, il filtering e l’embedding dei parametri DEVE essere implementata tramite i parametri: q, fields, embed

Note

How to detect if a request requires pagination? Can we just check if it has parameters? Whether the response has an array field?

We built a rule for exactly this purpose:

• https://git.fitko.de/fit-connect/api/-/blob/main/.spectral.yml#L27
• https://git.fitko.de/fit-connect/api/-/blob/main/functions/pagination-response.js

Thanks! I'll check it. OT: how are you going to manage the switch to Spectral 6? Some rules stopped working...

Moreover w are now supporting versioned rulesets. we are renaming rules because Spectral 6 doesn't allow custom properties in rules: we had then to replace tags with some other mechanism.

All security rules will start with sec- Some of them are now mandatory so they will be moved under rules/ whereas security/ will contain optional security rules.

We have to identify a prefix for Mandatory Italian rules which are stricter than best practices, eg ita- Otherwise specific keywords can be in the description... We've to think about it.

To use versioned ruleset, see https://github.com/italia/api-oas-checker/blob/master/README.en.md#ci-mode-versioned-rulesets @codedust

If you need a specific untagged version from the past, just let me know the date and I'll create the missing tag.

We did not look into switching to Spectral 6 yet, tbh. For now, we're stuck with Spectral 5.

If you need a specific untagged version from the past, just let me know the date and I'll create the missing tag. Thanks! We will return to your offer if needed.

Consider extending fitko pagination rules to support configurable parameters

@AlessioMarinelli I updated the description. See the example schema for pagination fields. https://italia.github.io/api-oas-checker/?url=https://teamdigitale.github.io/openapi/master/definitions.yaml

Feel free to post your example OAS3 and I'll provide some comments on it.