Campos en OpenAPI

OpenAPI (anteriormente conocido como Swagger) es una especificación para crear API (interfaces de programación de aplicaciones). Proporciona una forma estándar de definir, documentar y consumir API RESTful. La especificación OpenAPI está escrita en formato YAML o JSON e incluye una serie de campos que se utilizan para definir varios aspectos de la API.

Estos son algunos de los campos más utilizados en OpenAPI:

openapi: especifica la versión de la especificación OpenAPI que se está utilizando.
info: contiene información sobre la API, como título, descripción, versión y detalles de contacto.
servers: especifica los servidores en los que está alojada la API.
paths: Define los puntos finales (URL) de la API y los métodos HTTP (GET, POST, PUT, DELETE, etc.) que se pueden usar para acceder a ellos.
components: contiene elementos reutilizables de la API, como esquemas, esquemas de seguridad y respuestas.
security: especifica los esquemas de seguridad que utiliza la API.
tags: proporciona metadatos para agrupar y organizar operaciones y puntos finales.
externalDocs: Contiene enlaces a documentación externa relacionada con la API.

Estos son solo algunos ejemplos de los campos que se pueden usar en una especificación OpenAPI. La lista completa de campos se puede encontrar en la documentación de especificación oficial de OpenAPI.

¿Cómo contribuye Apigit a rellenar estos campos?

Si bien no todos los campos en una especificación de OpenAPI son estrictamente obligatorios, hay ciertos campos que deben incluirse para garantizar que la especificación sea válida y completa. Estos son algunos de los campos imprescindibles en una especificación de OpenAPI:

openapi: especifica la versión de la especificación OpenAPI que se está utilizando. Este campo es obligatorio y debe incluirse en el nivel raíz de la especificación.
info: contiene información sobre la API, como título, descripción, versión y detalles de contacto. Este campo es obligatorio y también debe incluirse en el nivel raíz de la especificación.
paths: Define los puntos finales (URL) de la API y los métodos HTTP (GET, POST, PUT, DELETE, etc.) que se pueden usar para acceder a ellos. Este campo también es obligatorio y debe incluirse en el nivel raíz de la especificación.
servers: especifica los servidores en los que está alojada la API. Este campo no es estrictamente obligatorio, pero se recomienda incluirlo para proporcionar información sobre los servidores que alojan la API.
components: contiene elementos reutilizables de la API, como esquemas, esquemas de seguridad y respuestas. Este campo no es estrictamente obligatorio, pero se recomienda incluirlo para una mejor organización y reutilización de la especificación.

Estos son los campos esenciales que deben incluirse en una especificación OpenAPI para garantizar que sea válida y completa. Otros campos comosecurity,tags, yexternalDocs también se pueden incluir según las necesidades de la API y el nivel de detalle requerido en la especificación.

Para agregar una especificación de API a su tablero de Apigit, haga clic en el signo "+" ubicado en la esquina superior izquierda. Ingrese un nombre de ruta, como "test/test.json", junto con otra información relevante como el "título" y la "versión". Un archivo vacío ayudará a completar todos estos campos obligatorios.

Crear un archivo de especificaciones vacío

Entonces su código json sería como el siguiente.

{
  "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": {}
  }
}

¿Cómo ayuda más Apigit?

Para ilustrar cómo Apigit ayuda a completar un campo en formato de formulario, aquí hay algunos ejemplos. AgregarField parameter enForm

Entonces su código json sería como el siguiente.

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

AgregarField path enForm

Entonces su código json sería como el siguiente.

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