Explore API Design: Write a Schema with an AI Assistant, Then Import It

Understanding Schemas in OpenAPI 3.0

In OpenAPI 3.0, a schema is used to define the data structure of an API's request or response payload. It is a way to describe the expected format and data types of the information being transmitted.

A schema is defined using JSON Schema, which is a standard for describing the structure and validation rules for JSON data. The OpenAPI 3.0 specification includes an extended subset of JSON Schema that provides additional features specific to API documentation, such as the ability to describe response codes and headers.

The schema definition can be included in an OpenAPI document in the components section, where it can be referenced by other parts of the document. A schema can be defined for a request or response body, a request or response header, or a parameter.

Some of the properties that can be defined in a schema include:

type: The data type of the property, such as string, integer, boolean, or array.

format: A format for the data type, such as date-time for a timestamp or email for an email address.

properties: A list of properties and their corresponding schemas for an object.

items: The schema for each item in an array.

required: A list of required properties for an object.

enum: A list of possible values for a property.

By defining schemas in OpenAPI 3.0, API developers can ensure that their APIs are well-documented and that clients can easily understand the expected format and data types of the information being transmitted.

Schemas in Apigit Api design

APIGit has no built-in AI: the assistant in this post is an external one, such as ChatGPT, and APIGit is where you bring the result.

Navigate to your repository and choose one spec file, in the default view mode, click on the ✏️ icon located in the bottom left-hand corner. In the editor, you can switch between the Form view and the Code view. A schema such as User, with its six fields, is simple but still takes time to write by hand. An external AI assistant can help simplify the process even further.

Bring an AI assistant's result into Apigit

You only need to generate a sample data for your object.

{
  "id": 10,
  "username": "theUser",
  "firstName": "John",
  "lastName": "James",
  "email": "john@email.com",
  "password": "12345",
  "phone": "12345",
  "userStatus": 1
}

And then ask ChatGPT to give you the schema data.

Schemas generated by ChatGPT

What you will get is as below.

{
    "$schema": "http://json-schema.org/draft-07/schema#",
        "title": "User",
        "type": "object",
        "properties": {
        "id": {
            "type": "integer",
                "description": "The ID of the user",
                "example": 10
        },
        "username": {
            "type": "string",
                "description": "The username of the user",
                "example": "theUser"
        },
        "firstName": {
            "type": "string",
                "description": "The first name of the user",
                "example": "John"
        },
        "lastName": {
            "type": "string",
                "description": "The last name of the user",
                "example": "James"
        },
        "email": {
            "type": "string",
                "format": "email",
                "description": "The email address of the user",
                "example": "john@email.com"
        },
        "password": {
            "type": "string",
                "description": "The password of the user",
                "example": "12345"
        },
        "phone": {
            "type": "string",
                "description": "The phone number of the user",
                "example": "12345"
        },
        "userStatus": {
            "type": "integer",
                "description": "The status of the user",
                "example": 1
        }
    },
    "required": ["id", "username", "firstName", "lastName", "email", "password", "phone", "userStatus"]
}

There are two ways to bring the result into your repository.

To keep it as a JSON Schema file of its own:

1. Save the result as a .json file on your computer.
2. Click on the + sign above the file list.
3. Choose Json Schema Spec, then import Json Schema spec.
4. Drop the file into the dialog and enter a path name for it.

To add it to an OpenAPI spec file:

1. Open the spec file in edit mode and switch to the Code view.
2. Paste the type, properties and required parts under components > schemas > User, leaving out the $schema line.
3. Switch to the Form view to check the result.

An AI assistant can make mistakes, so check its work before you commit it.

1. Review the schema carefully and check for any errors or inconsistencies.
2. Make any necessary changes to the schema to correct errors or add missing information.