OpenAPI Structure and Best Practices

OpenAPI (formerly known as Swagger) is a specification for building APIs (Application Programming Interfaces). It provides a standard way of defining, documenting, and consuming RESTful APIs. The OpenAPI specification is written in YAML or JSON format and includes a number of fields that are used to define various aspects of the API.

Here are some of the most commonly used fields in OpenAPI:

1. openapi: Specifies the version of the OpenAPI specification being used.
2. info: Contains information about the API, such as title, description, version, and contact details.
3. servers: Specifies the server(s) that the API is hosted on.
4. paths: Defines the endpoints (URLs) of the API and the HTTP methods (GET, POST, PUT, DELETE, etc.) that can be used to access them.
5. components: Contains reusable elements of the API, such as schemas, security schemes, and responses.
6. security: Specifies the security schemes that the API uses.
7. tags: Provides metadata for grouping and organizing operations and endpoints.
8. externalDocs: Contains links to external documentation related to the API.

These are just a few examples of the fields that can be used in an OpenAPI specification. The full list of fields can be found in the official OpenAPI specification documentation.

How does Apigit contribute to filling in these fields?

While not all fields in an OpenAPI specification are strictly required, there are certain fields that must be included to ensure that the specification is valid and complete. Here are some of the must-have fields in an OpenAPI specification:

1. openapi: Specifies the version of the OpenAPI specification being used. This field is required and must be included at the root level of the specification.

2. info: Contains information about the API, such as title, description, version, and contact details. This field is required and must also be included at the root level of the specification.

3. paths: Defines the endpoints (URLs) of the API and the HTTP methods (GET, POST, PUT, DELETE, etc.) that can be used to access them. This field is also required and must be included at the root level of the specification.

4. servers: Specifies the server(s) that the API is hosted on. This field is not strictly required, but it is recommended to include it to provide information on the server(s) hosting the API.

5. components: Contains reusable elements of the API, such as schemas, security schemes, and responses. This field is not strictly required, but it is recommended to include it for better organization and reusability of the specification.

These are the essential fields that must be included in an OpenAPI specification to ensure that it is valid and complete. Other fields such as security, tags, and externalDocs may also be included depending on the needs of the API and the level of detail required in the specification.

To add an API specification to your repository, click on the "+" sign above the file list. Input a pathname, such as "test/test.json," along with other relevant information like the "title" and "version." An empty file will help to fill all these required fields.

Then your json code would be like below.

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

How does Apigit assists more?

To illustrate how Apigit assists in filling a field in Form format, here are some examples. The Form view of a spec file

Add a parameter under components in Form.

Then your json code would be like below.

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

Add a path in Form.

Then your json code would be like below.

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

To explore more, you can try to fill other fields in Form and switch the view between Form and Code.

The Code view of the same file