Prima API nell'interfaccia utente di Swagger

Swagger UI è uno strumento open source che genera un'interfaccia utente per una specifica OpenAPI, consentendo agli utenti di visualizzare e interagire con gli endpoint API. Lo strumento è sviluppato e gestito dal progetto Swagger, che ora fa parte della più ampia iniziativa OpenAPI.

L'interfaccia utente di Swagger può essere utilizzata per testare ed esplorare rapidamente un'API senza la necessità di strumenti o software aggiuntivi. Una volta fornita una specifica OpenAPI, l'interfaccia utente di Swagger genera una pagina di documentazione interattiva che include informazioni su endpoint, parametri, risposte e altro dell'API. L'interfaccia utente viene generata dinamicamente in base alle informazioni fornite nella specifica, il che significa che le modifiche apportate all'API si rifletteranno automaticamente nella documentazione.

Oltre a fornire funzionalità di documentazione e test, l'interfaccia utente di Swagger supporta anche varie funzionalità come l'evidenziazione della sintassi, la convalida della risposta e la generazione di codice. Lo strumento può essere utilizzato con API create utilizzando qualsiasi linguaggio di programmazione e può essere personalizzato in modo che corrisponda al marchio e allo stile dell'API.

Oggi aggiungeremo la nostra prima API nell'interfaccia utente di Swagger.

Campo del server

In una specifica OpenAPI, l'oggetto server viene utilizzato per definire le informazioni sul server che ospita l'API. L'oggetto server include diversi campi che possono essere utilizzati per fornire informazioni come l'URL, il protocollo e la descrizione del server. Ecco i campi che possono essere inclusi in un oggetto server:

url: Questo campo specifica l'URL di base del server. È un campo obbligatorio e deve essere incluso nell'oggetto Server.

description: Questo campo fornisce una descrizione del server. È un campo facoltativo e può essere incluso per fornire informazioni aggiuntive sul server.

variables: Questo campo viene utilizzato per definire le variabili che possono essere utilizzate nel campo url. Le variabili sono racchiuse tra parentesi graffe ({}) e possono essere utilizzate per rappresentare parti dell'URL che possono essere personalizzate per diversi ambienti o casi d'uso.

scheme: Questo campo specifica il protocollo di comunicazione utilizzato dal server (es. HTTP, HTTPS, ecc.). È un campo facoltativo e il valore predefinito è "http" se non specificato.

headers: Questo campo viene utilizzato per specificare eventuali intestazioni che devono essere incluse nelle richieste al server. È un campo facoltativo e può essere utilizzato per fornire informazioni aggiuntive o credenziali di autenticazione.

Ecco un esempio di un oggetto server con tutti i campi inclusi:

"servers": [
  {
    "url": "https://api.example.com/{version}",
    "description": "Example API Server",
    "variables": {
      "version": {
        "enum": ["v1", "v2"],
        "default": "v1"
      }
    },
    "scheme": "https",
    "headers": {
      "X-API-Key": {
        "description": "API key",
        "required": true
      }
    }
  }
]

Ecco un esempio di un oggetto server per la nostra prima API. Aggiungi un server.

Campo dell'etichetta

In una specifica OpenAPI, l'oggetto Tag viene utilizzato per definire un tag per un insieme di operazioni correlate. L'oggetto tag include diversi campi che possono essere utilizzati per fornire informazioni come il nome del tag, la descrizione e le operazioni associate. Ecco i campi che possono essere inclusi in un Oggetto Tag:

name: Questo campo specifica il nome del tag. È un campo obbligatorio e deve essere incluso nell'Oggetto Tag.

description: Questo campo fornisce una descrizione del tag. È un campo facoltativo e può essere incluso per fornire ulteriori informazioni sul tag.

externalDocs: Questo campo fornisce un riferimento alla documentazione aggiuntiva per il tag. È un campo facoltativo e può essere utilizzato per fornire ulteriori informazioni o risorse relative al tag.

x-tag-info: Questo campo è un campo di estensione che può essere utilizzato per fornire ulteriori informazioni sul tag. È un campo facoltativo e può essere utilizzato per fornire informazioni personalizzate o metadati sul tag.

Ecco un esempio di un oggetto tag con tutti i campi inclusi:

"tags": [
  {
    "name": "pets",
    "description": "Operations related to pets",
    "externalDocs": {
      "description": "Find more info here",
      "url": "https://example.com/pets/info"
    },
    "x-tag-info": {
      "owner": "John Smith"
    }
  }
]

Ecco un esempio di Tag Object per la nostra prima API. Aggiungi un'etichetta.

Campo dello schema

In una specifica OpenAPI, l'oggetto schema viene utilizzato per descrivere la struttura e i tipi di dati di un oggetto. L'oggetto schema include diversi campi che possono essere utilizzati per fornire informazioni come il tipo, il formato e le proprietà dello schema. Ecco i campi che possono essere inclusi in un oggetto schema:

title: Questo campo specifica il titolo dello schema. È un campo facoltativo e può essere incluso per fornire un titolo leggibile per lo schema.

type: Questo campo specifica il tipo di schema. È un campo obbligatorio e può essere uno dei diversi valori possibili, come "stringa", "numero", "intero", "booleano", "array" o "oggetto".

format: Questo campo specifica il formato dello schema. È un campo facoltativo e può essere utilizzato per specificare ulteriormente il tipo di dati dello schema. Ad esempio, se il tipo è "stringa", il campo formato può essere utilizzato per indicare che la stringa è una data o un'ora.

description: Questo campo fornisce una descrizione dello schema. È un campo facoltativo e può essere incluso per fornire ulteriori informazioni sullo schema.

properties: Questo campo specifica le proprietà di uno schema oggetto. È un campo facoltativo e può essere utilizzato per definire le proprietà ei tipi di dati delle proprietà di un oggetto.

items: Questo campo specifica lo schema degli elementi in un array. È un campo facoltativo e può essere utilizzato per definire il tipo di dati degli elementi di un array.

required: Questo campo specifica le proprietà richieste di uno schema oggetto. È un campo facoltativo e può essere utilizzato per specificare quali proprietà di uno schema oggetto sono richieste.

example: Questo campo fornisce un esempio dello schema. È un campo facoltativo e può essere utilizzato per fornire un valore di esempio per lo schema.

Ecco un esempio di un oggetto schema con tutti i campi inclusi:

{
  "type": "object",
  "title": "Person",
  "description": "A person schema",
  "properties": {
    "name": {
      "type": "string"
    },
    "age": {
      "type": "integer"
    },
    "email": {
      "type": "string",
      "format": "email"
    }
  },
  "required": [
    "name"
  ],
  "example": {
    "name": "John Smith",
    "age": 30,
    "email": "john.smith@example.com"
  }
}

Ecco un esempio di un oggetto schema per la nostra prima API. Aggiungi uno schema.

Campo di sentieri

In una specifica OpenAPI, l'oggetto percorsi viene utilizzato per definire gli endpoint disponibili (o route) e le operazioni su tali endpoint. L'oggetto percorsi è una mappa valore-chiave in cui le chiavi sono i percorsi dell'endpoint ei valori sono oggetti elemento percorso. Ecco i campi che possono essere inclusi in un oggetto Path Item:

Metodo HTTP: esistono diversi metodi HTTP, come GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS e TRACE. Questo campo specifica il metodo HTTP supportato dall'endpoint.

summary: questo campo fornisce un breve riepilogo dell'operazione dell'endpoint.

description: Questo campo fornisce una descrizione dettagliata dell'operazione dell'endpoint.

parameters: questo campo specifica i parametri accettati dall'operazione dell'endpoint. Può essere un array di oggetti parametro o un riferimento a una definizione di parametro.

requestBody: questo campo specifica il corpo della richiesta previsto dall'operazione dell'endpoint. È un campo facoltativo e può essere un oggetto RequestBody o un riferimento a una definizione del corpo della richiesta.

responses: questo campo specifica le possibili risposte che possono essere restituite dall'operazione dell'endpoint. È una mappa valore-chiave in cui le chiavi sono i codici di stato HTTP ei valori sono oggetti risposta.

callbacks: Questo campo specifica una mappa di possibili callback relativi all'operazione padre. Ogni valore nella mappa è un oggetto Callback.

deprecated: questo campo indica se l'operazione dell'endpoint è deprecata e non deve essere utilizzata.

Ecco un esempio di oggetto Path Item che include tutti questi campi:

{
  "/pets": {
    "get": {
      "summary": "Get a list of pets",
      "description": "Returns a list of pets that are available for adoption.",
      "parameters": [
        {
          "name": "limit",
          "in": "query",
          "description": "The maximum number of pets to return.",
          "required": false,
          "schema": {
            "type": "integer"
          }
        }
      ],
      "responses": {
        "200": {
          "description": "A list of pets.",
          "content": {
            "application/json": {
              "schema": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Pet"
                }
              }
            }
          }
        },
        "400": {
          "description": "Invalid input."
        },
        "401": {
          "description": "Unauthorized."
        },
        "500": {
          "description": "Server error."
        }
      }
    }
  }
}

Ecco un esempio di Paths Object per la nostra prima API. Aggiungi un percorso.

L'interfaccia utente di Swagger può essere utilizzata per testare rapidamente

ILTry it out La funzionalità nell'interfaccia utente di Swagger consente agli utenti di interagire con un'API inviando richieste e ricevendo risposte. Fornisce un'interfaccia utente per testare l'API senza dover scrivere codice o utilizzare uno strumento separato.

Quando fai clic sulTry it out accanto a un'operazione API nell'interfaccia utente di Swagger, puoi inserire i valori per i parametri dell'operazione e inviare una richiesta all'API. L'interfaccia utente di Swagger visualizzerà quindi la risposta restituita dall'API. Ciò consente di testare e convalidare rapidamente il comportamento di un'API senza dover uscire dall'interfaccia dell'interfaccia utente di Swagger.

ILTry it out La funzionalità può anche aiutarti a esplorare le capacità di un'API e capire come utilizzarla in modo efficace. Interagendo con un'API in tempo reale, puoi vedere come risponde a diverse richieste e saperne di più sui dati che restituisce.

Ecco un esempio diTry it out per la nostra prima api. Try it out