Documenting Schemas and Models

Relevant source files

The following files were used as context for generating this wiki page:

• api-reference/openapi.json
• docs.json
• README.md
• api-reference/introduction.mdx
• api-reference/endpoint/get.mdx
• api-reference/endpoint/create.mdx

This document outlines how data schemas and models are defined, structured, and utilized within the project's API documentation. The primary source of truth for all API data structures is the OpenAPI specification file, which defines the shape of requests, responses, and reusable components. These definitions are then rendered as part of the API reference documentation.

The system relies on api-reference/openapi.json to declare all data models under the components/schemas object. These schemas are then referenced throughout the API paths and webhooks definitions to ensure consistency. The documentation structure, defined in docs.json, creates the navigation that leads developers to pages detailing these endpoints and their associated schemas.

Sources: api-reference/openapi.json, docs.json

OpenAPI Schema Definitions

All data models for the API are centralized within the components/schemas section of the api-reference/openapi.json file. This approach promotes reusability and provides a single source for understanding the data structures used across different endpoints.

Sources: api-reference/openapi.json:165-220

Core Schemas

The API defines three primary schemas: Plant, NewPlant, and Error.

• Plant: The base representation of a plant, containing its name and an optional tag.
• NewPlant: An extension of the Plant schema that includes a required id. This model is used when creating a new plant or receiving a webhook notification.
• Error: A standardized structure for returning error messages, containing an error code and a message string.

Sources: api-reference/openapi.json:166-220

The relationship between Plant and NewPlant is defined using allOf, indicating that NewPlant inherits all properties from Plant and adds its own.

This class diagram illustrates the inheritance structure of the data models.

Schema Details

Plant Schema

This schema represents a plant in the system. The name is a required field.

Property	Type	Description	Required
name	string	The name of the plant	Yes
tag	string	Tag to specify the type	No

Sources: api-reference/openapi.json:167-185

"Plant": {
  "required": [
    "name"
  ],
  "type": "object",
  "properties": {
    "name": {
      "description": "The name of the plant",
      "type": "string"
    },
    "tag": {
      "description": "Tag to specify the type",
      "type": "string"
    }
  }
}

Sources: api-reference/openapi.json:167-185

NewPlant Schema

This schema is used for creating new plants and is composed of the Plant schema plus a required id.

Property	Type	Description	Required
name	string	The name of the plant (inherited)	Yes
tag	string	Tag to specify the type (inherited)	No
id	integer	Identification number of the plant	Yes

Sources: api-reference/openapi.json:186-203

"NewPlant": {
  "allOf": [
    {
      "$ref": "#/components/schemas/Plant"
    },
    {
      "required": [
        "id"
      ],
      "type": "object",
      "properties": {
        "id": {
          "description": "Identification number of the plant",
          "type": "integer",
          "format": "int64"
        }
      }
    }
  ]
}

Sources: api-reference/openapi.json:186-203

Error Schema

This schema provides a consistent format for all API error responses.

Property	Type	Description	Required
error	integer	Error code	Yes
message	string	Error message	Yes

Sources: api-reference/openapi.json:204-220

Schema Usage in API Endpoints

The defined schemas are referenced in API path definitions to specify the structure of request bodies and responses. This ensures that the data exchanged with the API conforms to the documented models.

Sources: api-reference/openapi.json:24-164, api-reference/endpoint/get.mdx, api-reference/endpoint/create.mdx

Endpoint Schema Mapping

The following diagram shows how different endpoints utilize the Plant, NewPlant, and Error schemas.

Example Flow: Creating a Plant

When a client sends a request to POST /plants, it must provide a request body that conforms to the NewPlant schema. If successful, the API returns a response body matching the Plant schema.

The sequence diagram below illustrates this interaction.

Integration with Documentation

The project uses Mintlify to build and display documentation. The structure of the documentation, particularly the API reference section, is defined in docs.json. This file maps navigation items to specific content files.

Sources: docs.json:1-100, README.md:14-19

The docs.json configuration for the API reference tab is as follows:

{
  "tab": "API reference",
  "groups": [
    {
      "group": "API documentation",
      "pages": [
        "api-reference/introduction"
      ]
    },
    {
      "group": "Endpoint examples",
      "pages": [
        "api-reference/endpoint/get",
        "api-reference/endpoint/create",
        "api-reference/endpoint/delete",
        "api-reference/endpoint/webhook"
      ]
    }
  ]
}

Sources: docs.json:48-71

This configuration ensures that the schemas defined in openapi.json are presented to the user through dedicated pages like api-reference/endpoint/get.mdx and api-reference/endpoint/create.mdx, which would detail the usage of the Plant and NewPlant schemas respectively.

Sources: docs.json:62-67, api-reference/introduction.mdx

Summary

The project employs a robust, schema-driven approach to API documentation. By defining all data models (Plant, NewPlant, Error) within a single openapi.json file, it establishes a single source of truth. These schemas are then consistently referenced across endpoint definitions for requests and responses. Finally, the docs.json file orchestrates the presentation of this information, creating a clear and navigable API reference for developers. This separation of concerns—definition, application, and presentation—results in documentation that is maintainable and accurate.

Sources: api-reference/openapi.json, docs.json, README.md