OpenAPI Specification Guide

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 (referenced in docs.json)
• api-reference/endpoint/get.mdx (referenced in docs.json)

The api-reference/openapi.json file defines the structure, endpoints, and data models for a sample "OpenAPI Plant Store" API. This specification, written in OpenAPI 3.1.0 format, serves as the single source of truth for generating the API reference documentation within this Mintlify project. It details every aspect of the API, from available server URLs and security schemes to the specific request and response formats for each endpoint.

This guide provides a comprehensive breakdown of the API as defined in the openapi.json file. The documentation pages themselves, such as the API Introduction and Endpoint Examples, are organized through the navigation configuration in docs.json.

Sources: api-reference/openapi.json:2-8, docs.json:16-47

API Overview

The API is titled "OpenAPI Plant Store" and is currently at version 1.0.0. It is designed as a sample to demonstrate OpenAPI specification features. All API requests are directed to a single server.

Property	Value	Source File
Title	OpenAPI Plant Store	api-reference/openapi.json:4
Version	1.0.0	api-reference/openapi.json:8
License	MIT	api-reference/openapi.json:6
Server URL	http://sandbox.mintlify.com	api-reference/openapi.json:11

Sources: api-reference/openapi.json:3-13

Security

The API is secured using Bearer Token authentication. All requests must include an Authorization header with a valid bearer token. This is defined globally for all paths.

"security": [
  {
    "bearerAuth": []
  }
]

Sources: api-reference/openapi.json:14-18, api-reference/openapi.json:210-216

The diagram below illustrates the basic authentication flow.

API Endpoints

The API provides endpoints for managing plants and a webhook for receiving notifications. The endpoints are defined under the paths object in the specification.

Method	Path	Description
GET	/plants	Returns all plants from the system.
POST	/plants	Creates a new plant in the store.
DELETE	/plants/{id}	Deletes a single plant based on the ID supplied.

Sources: api-reference/openapi.json:20-120

GET /plants

This endpoint retrieves a list of all available plants. It supports an optional query parameter to limit the number of results.

Parameters

Name	In	Description	Type	Format
limit	query	The maximum number of results to return	integer	int32

Responses

• 200 OK: Returns an array of Plant objects.
• 400 Bad Request: An unexpected error occurred, returns an Error object.

The following sequence diagram shows a successful request to fetch plants.

POST /plants

This endpoint creates a new plant. The plant data must be provided in the request body, conforming to the NewPlant schema.

Request Body

• Content-Type: application/json
• Schema: NewPlant

Responses

• 200 OK: The plant was created successfully, returns the new Plant object.
• 400 Bad Request: An unexpected error occurred, returns an Error object.

Sources: api-reference/openapi.json:56-89

DELETE /plants/{id}

This endpoint deletes a specific plant identified by its id. The id is a required path parameter.

Parameters

Name	In	Description	Type	Format	Required
id	path	ID of plant to delete	integer	int64	true

Responses

• 204 No Content: The plant was deleted successfully.
• 400 Bad Request: An unexpected error occurred, returns an Error object.

Sources: api-reference/openapi.json:91-120

Webhooks

The API defines a webhook to notify external systems when a new plant is added to the store.

POST /plant/webhook

This webhook is triggered when a new plant is created. It sends a POST request to a pre-configured URL with the new plant's data.

Request Body

• Description: Information about a new plant added to the store.
• Content-Type: application/json
• Schema: NewPlant

Response
The receiving service should return a 200 OK status to acknowledge successful receipt of the data.

Sources: api-reference/openapi.json:122-141

Data Models (Schemas)

The API uses several data models, defined under components/schemas, to ensure consistent data structures for requests and responses.

This diagram shows the relationship between the Plant and NewPlant schemas.

The NewPlant schema inherits all properties from Plant and adds an id.
Sources: api-reference/openapi.json:143-193

Plant Schema

This is the base model for a plant.

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:144-162

NewPlant Schema

This model is used when creating a new plant and includes an ID. It is composed of the Plant schema and an additional id property.

Property	Type	Format	Description	Required
id	integer	int64	Identification number of the plant	Yes

Sources: api-reference/openapi.json:163-182

Error Schema

This model is used for all 400 error responses.

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

Sources: api-reference/openapi.json:183-199

Documentation Structure

The API reference documentation is organized using the docs.json configuration file. It defines a dedicated "API reference" tab with groups for introduction and endpoint examples.

The following diagram illustrates the navigation structure for the API documentation.

This structure ensures that the documentation generated from openapi.json is presented in a logical and user-friendly manner.
Sources: docs.json:16-47, api-reference/introduction.mdx, api-reference/endpoint/get.mdx

Conclusion

The openapi.json file is a critical asset in this project, providing a machine-readable definition of the "OpenAPI Plant Store" API. It enables automated documentation generation, ensures consistency between the API and its documentation, and serves as a clear contract for API consumers. The structure of the documentation is managed by docs.json, which organizes the generated pages into a navigable format for developers.

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