Condividi tramite

Introduzione all'estensione Centro API di Azure per Visual Studio Code

  • Articolo

Per compilare, individuare, provare e usare le API nel centro API, è possibile usare l'estensione Centro API di Azure nell'ambiente di sviluppo di Visual Studio Code:

  • Creare API: consente di creare API individuabili per gli altri utenti registrandole nel centro API. Controlli di conformità della progettazione dell'API maiuscole/sinistra in Visual Studio Code con supporto di linting integrato. Assicurarsi che le nuove versioni dell'API non interrompano i consumer di API con il rilevamento delle modifiche che causa un'interruzione.

  • Individuare le API: esplorare le API nel centro API e visualizzarne i dettagli e la documentazione.

  • Provare le API: usare l'interfaccia utente di Swagger o il client REST per esplorare le richieste e le risposte dell'API.

  • Usare le API: generare client API SDK per il linguaggio preferito, tra cui JavaScript, TypeScript, .NET, Python e Java, usando il motore Microsoft Kiota che genera SDK per Microsoft Graph, GitHub e altro ancora.

Prerequisiti

Le estensioni di Visual Studio Code seguenti sono facoltative e necessarie solo per determinati scenari, come indicato:

Attrezzaggio

  1. Installare l'estensione Centro API di Azure per Visual Studio Code da Visual Studio Code Marketplace. Installare le estensioni facoltative in base alle esigenze.
  2. In Visual Studio Code, nella barra delle attività a sinistra selezionare Centro API.
  3. Se non si è connessi all'account Azure, selezionare Accedi ad Azure...e seguire le istruzioni per accedere. Selezionare un account Azure con il centro API (o i centri API) da cui si vogliono visualizzare le API. È anche possibile filtrare in base a sottoscrizioni specifiche se sono disponibili molte opzioni da visualizzare.

Registrare le API

Registrare un'API nel centro API direttamente da Visual Studio Code registrandola come operazione monouso o con una pipeline CI/CD.

  1. Usare il tasto di scelta rapida CTRL+MAIUSC+P per aprire il riquadro comandi. Digitare Centro API di Azure: registrare l'API e premere INVIO.
  2. Selezionare la modalità di registrazione dell'API con il centro API:
    • La procedura dettagliata è ideale per la registrazione monouso delle API.
    • CI/CD aggiunge una pipeline GitHub o Azure DevOps preconfigurata all'area di lavoro di Visual Studio Code attiva eseguita come parte di un flusso di lavoro CI/CD in ogni commit nel controllo del codice sorgente. È consigliabile eseguire l'inventario delle API con il centro API usando CI/CD per garantire che i metadati dell'API, incluse le specifiche e la versione, rimangano aggiornati nel centro API man mano che l'API continua a evolversi nel tempo.
  3. Completare i passaggi per la registrazione:
    • Per la procedura dettagliata, selezionare il Centro API per registrare le API con e rispondere a richieste con informazioni quali titolo API, tipo, fase del ciclo di vita, versione e specifica per completare la registrazione api.
    • Per CI/CD, selezionare GitHub o Azure DevOps, a seconda del meccanismo di controllo del codice sorgente preferito. Un'area di lavoro di Visual Studio Code deve essere aperta per l'estensione Centro API di Azure per aggiungere una pipeline all'area di lavoro. Dopo aver aggiunto il file, completare i passaggi documentati nel file della pipeline CI/CD stesso per configurare le variabili di ambiente e l'identità di Azure Pipeline/GitHub Action. Al push nel controllo del codice sorgente, l'API verrà registrata nel centro API.

Conformità alla progettazione dell'API

Per garantire la conformità della progettazione agli standard dell'organizzazione durante la compilazione delle API, l'estensione Centro API di Azure per Visual Studio Code offre il supporto integrato per l'esecuzione di linting delle specifiche API con spectrale.

  1. Usare il tasto di scelta rapida CTRL+MAIUSC+P per aprire il riquadro comandi. Digitare Centro API di Azure: Impostare la Guida di stile API attiva e premere Invio.
  2. Selezionare una delle regole predefinite specificate oppure, se l'organizzazione dispone già di una guida di stile, usare Selezionare file locale o URL remoto di input per specificare il set di regole attivo in Visual Studio Code. Premere INVIO.

Dopo aver impostato una guida di stile api attiva, l'apertura di un file di specifica basato su OpenAPI o AsyncAPI attiverà un'operazione di linting locale in Visual Studio Code. I risultati vengono visualizzati sia inline nell'editor che nella finestra Problemi (Visualizza>Problemi o CTRL+MAIUSC+M).

Screenshot del linting locale in Visual Studio Code.

Rilevamento di modifiche di rilievo

Quando si introducono nuove versioni dell'API, è importante assicurarsi che le modifiche introdotte non interrompano i consumer di API nelle versioni precedenti dell'API. L'estensione Centro API di Azure per Visual Studio Code semplifica questa operazione con il rilevamento delle modifiche di rilievo per i documenti delle specifiche OpenAPI basati su Ottica.

  1. Usare il tasto di scelta rapida CTRL+MAIUSC+P per aprire il riquadro comandi. Digitare Centro API di Azure: Rilevare le modifiche di rilievo e premere INVIO.
  2. Selezionare il primo documento di specifica dell'API da confrontare. Le opzioni valide includono le specifiche API disponibili nel centro API, un file locale o l'editor attivo in Visual Studio Code.
  3. Selezionare il secondo documento di specifica dell'API da confrontare. Le opzioni valide includono le specifiche API disponibili nel centro API, un file locale o l'editor attivo in Visual Studio Code.

Visual Studio Code aprirà una visualizzazione diff tra le due specifiche dell'API. Tutte le modifiche di rilievo vengono visualizzate sia inline nell'editor che nella finestra Problemi (Visualizza>Problemi o CTRL+MAIUSC+M).

Screenshot delle modifiche di rilievo rilevate in Visual Studio Code.

Generare un file di specifica OpenAPI dal codice API

Usare la potenza di GitHub Copilot con l'estensione Centro API di Azure per Visual Studio Code per creare un file di specifica OpenAPI dal codice API. Fare clic con il pulsante destro del mouse sul codice API, selezionare Copilot nelle opzioni e selezionare Genera documentazione dell'API. Verrà creato un file di specifica OpenAPI.

Dopo aver generato il file di specifica OpenAPI e aver verificato l'accuratezza, è possibile registrare l'API con il centro API di Azure usando il comando Centro API di Azure: Registrare l'API.

Individuare le API

Le risorse del centro API vengono visualizzate nella visualizzazione albero sul lato sinistro. Espandere una risorsa centro API per visualizzare API, versioni, definizioni, ambienti e distribuzioni.

Screenshot della visualizzazione albero di Centro API in Visual Studio Code.

Cercare le API all'interno di un Centro API usando l'icona di ricerca visualizzata nell'elemento della visualizzazione albero Apis.

Visualizzare la documentazione relativa alle API

È possibile visualizzare la documentazione per una definizione di API nel centro API e provare le operazioni API. Questa funzionalità è disponibile solo per le API basate su OpenAPI nel centro API.

  1. Espandere la visualizzazione della struttura ad albero del Centro API per visualizzare una definizione API.

  2. Fare clic con il pulsante destro del mouse sulla definizione e scegliere Apri documentazione API. Viene visualizzata una nuova scheda con l'interfaccia utente di Swagger per la definizione dell'API.

    Screenshot della documentazione dell'API in Visual Studio Code.

  3. Per provare l'API, selezionare un endpoint, selezionare Prova, immettere i parametri obbligatori e selezionare Esegui.

    Nota

    A seconda dell'API, potrebbe essere necessario fornire le credenziali di autorizzazione o una chiave API per provare l'API.

    Suggerimento

    È anche possibile usare l'estensione per generare la documentazione dell'API in Markdown, un formato facile da gestire e condividere con gli utenti finali. Fare clic con il pulsante destro del mouse sulla definizione e scegliere Genera markdown.

Generare un file HTTP

È possibile visualizzare un file .http basato sulla definizione dell'API nel centro API. Se l'estensione client REST è installata, è possibile effettuare richieste directory dall'editor di Visual Studio Code. Questa funzionalità è disponibile solo per le API basate su OpenAPI nel centro API.

  1. Espandere la visualizzazione della struttura ad albero del Centro API per visualizzare una definizione API.

  2. Fare clic con il pulsante destro del mouse sulla definizione e scegliere Genera file HTTP. Viene visualizzata una nuova scheda che esegue il rendering di un documento .http popolato dalla specifica dell'API.

    Screenshot della generazione di un file con estensione http in Visual Studio Code.

  3. Per effettuare una richiesta, selezionare un endpoint e selezionare Invia richiesta.

    Nota

    A seconda dell'API, potrebbe essere necessario fornire le credenziali di autorizzazione o una chiave API per effettuare la richiesta.

Generare il client API

Usare l'estensione Microsoft Kiota per generare un client API per la lingua preferita. Questa funzionalità è disponibile solo per le API basate su OpenAPI nel centro API.

  1. Espandere la visualizzazione della struttura ad albero del Centro API per visualizzare una definizione API.
  2. Fare clic con il pulsante destro del mouse sulla definizione e scegliere Genera client API. Viene visualizzato il riquadro Kiota OpenAPI Generator.
  3. Selezionare gli endpoint API e le operazioni HTTP da includere negli SDK.
  4. Selezionare Genera client API.

    1. Immettere i dettagli di configurazione relativi al nome dell'SDK, allo spazio dei nomi e alla directory di output.

    2. Selezionare la lingua per l'SDK generato.

      Screenshot di Kiota OpenAPI Explorer in Visual Studio Code.

Il client viene generato.

Per informazioni dettagliate sull'uso dell'estensione Kiota, vedere Estensione Microsoft Kiota per Visual Studio Code.

Esportare la specifica dell'API

È possibile esportare una specifica API da una definizione e quindi scaricarla come file.

Per esportare una specifica nella visualizzazione albero dell'estensione:

  1. Espandere la visualizzazione della struttura ad albero del Centro API per visualizzare una definizione API.

  2. Fare clic con il pulsante destro del mouse sulla definizione e scegliere Esporta documento specifica API. Viene visualizzata una nuova scheda che esegue il rendering di un documento di specifica dell'API.

    Screenshot dell'esportazione della specifica dell'API in Visual Studio Code.

È anche possibile esportare una specifica usando il riquadro comandi:

  1. Digitare il tasto di scelta rapida CTRL+MAIUSC+P per aprire il riquadro comandi.
  2. Selezionare Centro API di Azure: Esporta documento specifica API.
  3. Effettuare selezioni per passare a una definizione API. Viene visualizzata una nuova scheda che esegue il rendering di un documento di specifica dell'API.

Contenuto correlato