Condividi tramite

Analizzare le API nel centro API - Gestito da Microsoft

  • Articolo

Il centro API dell'organizzazione include funzionalità di linting gestite da Microsoft predefinite (anteprima) per analizzare le definizioni api per rispettare le regole di stile dell'organizzazione, generando report individuali e di riepilogo. L'analisi api identifica e consente di correggere gli errori comuni e le incoerenze nelle definizioni api.

Con l'analisi delle API:

  • Centro API di Azure analizza automaticamente le definizioni api ogni volta che si aggiunge o si aggiorna una definizione API. Le definizioni API vengono lintate per impostazione predefinita con un set di regole spectral:oas (guida di stile API).
  • I report di analisi API vengono generati nella portale di Azure, che illustrano come le definizioni API sono conformi alla guida di stile.
  • È possibile usare l'estensione Centro API di Azure per Visual Studio Code per personalizzare e testare la guida allo stile dell'API in locale e quindi distribuirla nel centro API.

Importante

Se si preferisce, è possibile abilitare l'analisi e il linting autogestito usando una funzione di Azure personalizzata, eseguendo l'override delle funzionalità predefinite. Disabilitare qualsiasi funzione usata per l'esecuzione di linting autogestito prima di usare l'analisi dell'API gestita.

Limiti

  • Attualmente vengono analizzati solo i documenti di specifica OpenAPI e AsyncAPI in formato JSON o YAML.
  • Attualmente, si configura un singolo set di regole, che viene applicato a tutte le definizioni OpenAPI del centro API.
  • Esistono limiti per il numero massimo di definizioni api analizzate. Il completamento dell'analisi può richiedere fino a 24 ore.

Prerequisiti

Visualizzare i report di analisi API

Visualizzare un riepilogo e i report di analisi per le definizioni dell’API nel portale di Azure. Dopo aver eseguito l'analisi delle definizioni dell’API, i report elencano errori, avvisi e informazioni in base alle regole della guida di stile dell’API configurata.

Nel report di analisi api esaminare anche il set di regole usato per l'analisi e la cronologia dei passaggi di linting.

Per visualizzare un riepilogo dell'analisi nel centro API:

  1. Nel portale, passare al proprio centro API.

  2. Nel menu a sinistra, in Governance, selezionare Analisi API. Viene visualizzato il riepilogo.

    Screenshot del riepilogo dell'analisi API nel portale.

  3. Facoltativamente, selezionare l'icona Report di analisi dell’API per una definizione dell’API. Viene visualizzato il report di analisi della definizione dell’API, come illustrato nello screenshot seguente.

    Screenshot di un report di analisi API nel portale.

    Suggerimento

    È anche possibile visualizzare il report di analisi dell’API selezionando Analisi dalla barra del menu della definizione dell’API.

Personalizzare il set di regole

È possibile usare l'estensione Centro API di Azure per Visual Studio Code per personalizzare il set di regole predefinito per il centro API o sostituirlo come guida allo stile dell'API dell'organizzazione. Ad esempio, è possibile estendere il set di regole o aggiungere funzioni personalizzate.

Per personalizzare o sostituire il set di regole:

  1. In Visual Studio Code selezionare l'icona del Centro API di Azure dalla barra attività.
  2. Aprire la .api-center-rules cartella nella radice della cartella di lavoro.
  3. Nella cartella per la risorsa del centro API aprire il ruleset.yml file.
  4. Modificare o sostituire il contenuto in base alle esigenze.
  5. Salvare le modifiche apportate a ruleset.yml.

Testare il set di regole in locale

Prima di distribuire il set di regole personalizzato nel centro API, convalidarlo in locale. L'estensione del Centro API di Azure per Visual Studio Code offre un supporto integrato per eseguire il linting della specifica API con Spectral.

  1. In Visual Studio Code, usare il tasto di scelta rapida CTRL+MAIUSC+P per aprire il riquadro comandi.

  2. Digitare Centro API di Azure: Impostare la Guida di stile API attiva e premere Invio.

  3. Scegliere Seleziona file locale e specificare il file ruleset.yml personalizzato. Premere INVIO.

    Attraverso questo passaggio, il set di regole personalizzato diventa la guida di stile dell'API attiva per il linting.

A questo punto, quando si apre un file di definizione dell'API basato su OpenAPI, viene automaticamente attivata un'operazione di linting locale in Visual Studio Code. I risultati vengono visualizzati inline nell'editor e nella finestra Problemi (Visualizza > Problemi o CTRL+MAIUSC+M).

Suggerimento

Gli sviluppatori di API dell'organizzazione possono anche usare questa funzionalità di linting locale per migliorare le definizioni api prima di registrare le API nel centro API.

Screenshot del linting di una definizione dell’API in Visual Studio Code.

Esaminare i risultati del linting. Apportare le modifiche necessarie al set di regole e continuare a testarlo in locale fino a quando non esegue la modalità desiderata.

Distribuire il set di regole al centro API

Per distribuire il set di regole personalizzato al centro API:

  1. In Visual Studio Code selezionare l'icona del Centro API di Azure dalla barra attività.
  2. Nel riquadro Centro API, espandere la risorsa del centro API in cui è stato personalizzato il set di regole.
  3. Fare clic con il pulsante destro del mouse su Regole e selezionare Distribuisci regole nel Centro API.

Dopo che le regole sono state distribuite correttamente nel centro API, viene visualizzato un messaggio di notifica. Il motore di linting usa il set di regole aggiornato per analizzare le definizioni dell’API.

Per vedere i risultati del linting con il set di regole aggiornato, visualizzare i report di analisi dell’API nel portale.

Contenuto correlato