Convalida le specifiche dell'API

Questa pagina si applica ad Apigee e Apigee hybrid.

Anteprima - Apigee API hub linting feature

Questa funzionalità è soggetta ai "Termini delle Offerte pre-GA" nella sezione Termini generali del servizio dei Termini specifici dei servizi. Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per saperne di più, consulta le descrizioni della fase di lancio.

L'hub API fornisce un linter Spectral (strumento di convalida) integrato che convalida la specifica OpenAPI della tua API. Poco dopo aver aggiunto una specifica OpenAPI alla versione dell'API, lo strumento di convalida (abilitato per impostazione predefinita) convalida la specifica e segnala i risultati nella console Google Cloud.

Nota: in questo argomento, i termini linting e validating vengono utilizzati in modo intercambiabile. Entrambi i termini hanno lo stesso significato.

Disattivare la convalida delle specifiche

Per impostazione predefinita, il lint è attivo. Per disattivare il lint, nella console Google Cloud, vai alla pagina Hub API > Impostazioni > Azioni e poi nella sezione Linting, disattiva l'opzione Linting.

Guida di stile

Una guida di stile è un insieme di regole in base alle quali l'hub API convalida una specifica OpenAPI. L'hub API utilizza una guida di stile predefinita per convalidare le specifiche OpenAPI. Per le regole della guida di stile predefinite, consulta Regole OpenAPI.

Nota: per aggiungere le tue regole personalizzate, devi creare una nuova guida di stile che espanda quella predefinita. Dopo aver aggiunto le regole personalizzate nella nuova guida di stile, devi caricarla nell'hub API.

Carica una nuova guida di stile

Console

Per caricare una nuova guida di stile:

1. Crea un nuovo stile estendendo la guida di stile predefinita. Per ulteriori informazioni, vedi Creare un insieme di regole.
   Nota: un passaggio di convalida eseguito sul caricamento genera un errore se un URL viene visualizzato nella proprietà extends del tuo insieme di regole. Ad esempio, questa è una proprietà illegale e causerà l'errore del caricamento: extends: [spectral:oas", "https://mystyle.com/"].

2. Nella console Google Cloud, vai alla pagina Hub API > Impostazioni > Azioni.

3. Nella sezione Linting, fai clic su Carica nuovo documento di stile.
4. Carica il nuovo documento di stile (creato nel passaggio 1), quindi fai clic su Salva.

API REST

Per caricare una nuova guida di stile per il linting, invia una richiesta PATCH alla seguente API:

https://apihub.googleapis.com/v1/projects/PROJECT/locations/LOCATION/plugins/standard-linter/styleGuide?update_mask=contents

Per ulteriori informazioni sull'API, consulta UpdateStyleGuide.

Nota: un passaggio di convalida eseguito sul caricamento genera un errore se nella proprietà extends del tuo insieme di regole è presente un URL. Ad esempio, questa è una proprietà costruita illegalmente e causerà il fallimento del caricamento: extends: [spectral:oas", "https://mystyle.com/"].

L'esempio seguente mostra la chiamata API per caricare una guida di stile.

curl \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{"name":"projects/test-project-1/locations/us-central1/plugins/standard-linter/styleGuide",
"contents":{  "contents": "ZXh0ZW5kczogWyJzcGVjdHJhbDpvYXMiXQo=",
  "mimeType": "text/yaml"}}' \ 
-X PATCH \
https://apihub.googleapis.com/v1/projects/test-project-1/locations/us-central1/plugins/standard-linter/styleGuide?update_mask=contents  

Scarica la guida di stile predefinita

Per scaricare la guida di stile predefinita utilizzata dall'hub API per il linting, segui questi passaggi:

1. Nella console Google Cloud, vai alla pagina Hub API > Impostazioni > Azioni.

2. Nella sezione Linting, fai clic su Scarica il documento di stile predefinito. In questo modo, il documento di stile predefinito viene scaricato sul tuo sistema locale.

Scarica la guida di stile più recente

Console

Per scaricare la guida di stile attualmente utilizzata da API Hub per il linting, segui questi passaggi:

1. Nella console Google Cloud, vai alla pagina Hub API > Impostazioni > Azioni.

2. Nella sezione Linting, fai clic su Scarica l'ultimo documento di stile. In questo modo il documento di stile predefinito viene scaricato sul tuo sistema locale.

API REST

Per scaricare la guida allo stile attualmente utilizzata dall'hub API per il linting, invia una richiesta GET alla seguente API:

https://apihub.googleapis.com/v1/projects/PROJECT/locations/LOCATION/plugins/standard-linter/styleGuide:contents

Per ulteriori informazioni sull'API, consulta GetStyleGuide.

L'esempio seguente mostra la chiamata API per scaricare la guida di stile corrente.

curl -X \
GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  https://apihub.googleapis.com/v1/projects/test-project-1/locations/us-central1/plugins/standard-linter/styleGuide:contents