Campi in OpenAPI

OpenAPI (precedentemente noto come Swagger) è una specifica per la creazione di API (Application Programming Interface). Fornisce un modo standard per definire, documentare e utilizzare le API RESTful. La specifica OpenAPI è scritta in formato YAML o JSON e include una serie di campi utilizzati per definire vari aspetti dell'API.

Ecco alcuni dei campi più comunemente utilizzati in OpenAPI:

1. openapi: specifica la versione della specifica OpenAPI utilizzata.
2. info: contiene informazioni sull'API, come titolo, descrizione, versione e dettagli di contatto.
3. servers: specifica i server su cui è ospitata l'API.
4. paths: definisce gli endpoint (URL) dell'API e i metodi HTTP (GET, POST, PUT, DELETE, ecc.) che possono essere utilizzati per accedervi.
5. components: contiene elementi riutilizzabili dell'API, come schemi, schemi di sicurezza e risposte.
6. security: specifica gli schemi di sicurezza utilizzati dall'API.
7. tags: fornisce i metadati per il raggruppamento e l'organizzazione delle operazioni e degli endpoint.
8. externalDocs: contiene collegamenti a documentazione esterna relativa all'API.

Questi sono solo alcuni esempi dei campi che possono essere utilizzati in una specifica OpenAPI. L'elenco completo dei campi è disponibile nella documentazione ufficiale della specifica OpenAPI.

In che modo Apigit contribuisce a compilare questi campi?

Sebbene non tutti i campi in una specifica OpenAPI siano strettamente obbligatori, ci sono alcuni campi che devono essere inclusi per garantire che la specifica sia valida e completa. Ecco alcuni dei campi indispensabili in una specifica OpenAPI:

1. openapi: specifica la versione della specifica OpenAPI utilizzata. Questo campo è obbligatorio e deve essere incluso al livello principale della specifica.

2. info: contiene informazioni sull'API, come titolo, descrizione, versione e dettagli di contatto. Questo campo è obbligatorio e deve essere incluso anche a livello principale della specifica.

3. paths: definisce gli endpoint (URL) dell'API e i metodi HTTP (GET, POST, PUT, DELETE, ecc.) che possono essere utilizzati per accedervi. Anche questo campo è obbligatorio e deve essere incluso al livello principale della specifica.

4. servers: specifica i server su cui è ospitata l'API. Questo campo non è strettamente obbligatorio, ma si consiglia di includerlo per fornire informazioni sui server che ospitano l'API.

5. components: contiene elementi riutilizzabili dell'API, come schemi, schemi di sicurezza e risposte. Questo campo non è strettamente obbligatorio, ma si consiglia di includerlo per una migliore organizzazione e riusabilità della specifica.

Questi sono i campi essenziali che devono essere inclusi in una specifica OpenAPI per garantire che sia valida e completa. Altri campi comesecurity,tags, EexternalDocs può anche essere incluso a seconda delle esigenze dell'API e del livello di dettaglio richiesto nella specifica.

Per aggiungere una specifica API alla tua dashboard Apigit, fai clic sul segno "+" situato nell'angolo in alto a sinistra. Inserisci un percorso, ad esempio "test/test.json", insieme ad altre informazioni pertinenti come "titolo" e "versione". Un file vuoto aiuterà a riempire tutti questi campi obbligatori.

Crea un file spec vuoto

Quindi il tuo codice json sarebbe come di seguito.

{
  "openapi": "3.0.3",
  "info": {
    "title": "titlet",
    "description": "just a test",
    "termsOfService": "",
    "contact": {
      "email": ""
    },
    "license": {
      "name": "Apache 2.0",
      "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
    },
    "version": "1.0"
  },
  "externalDocs": {
    "description": "Find out more about spec",
    "url": ""
  },
  "servers": [],
  "tags": [
    {
      "name": "Default",
      "description": ""
    }
  ],
  "paths": {},
  "components": {
    "schemas": {},
    "securitySchemes": {}
  }
}

In che modo Apigit aiuta di più?

Per illustrare come Apigit assiste nella compilazione di un campo in formato Form, ecco alcuni esempi. AggiungereField parameter InForm

Quindi il tuo codice json sarebbe come di seguito.

"components": {
    "schemas": {},
    "securitySchemes": {},
    "parameters": {
      "petId": {
        "in": "path",
        "required": true,
        "description": "",
        "schema": {
          "type": "string"
        },
        "name": "PetId"
      }
    }
  }

AggiungereField path InForm

Quindi il tuo codice json sarebbe come di seguito.

"paths": {
    "/getPet/{petId}": {
      "get": {
        "description": "",
        "operationId": "",
        "tags": [],
        "parameters": [],
        "requestBody": {},
        "responses": {
          "511": {}
        }
      },
      "parameters": [
        {
          "$ref": "#/components/parameters/petId"
        }
      ]
    }
  },

Per esplorare di più, puoi provare a compilare altri campiForm e cambia la visualizzazione traForm ECode.