All available API v2 endpoints must appear on the API v2 page in the Vanilla dashboard. Addons augmenting Vanilla’s API v2 capabilities must include valid OpenAPI v3 documentation to describe those changes.
You should write your endpoint's OpenAPI specification before you write the endpoint itself. This would also be a good opportunity to get a sign-off from a team lead to ensure the endpoint's conventions match Vanilla's best practices.
Writing a valid OpenAPI v3 endpoint definitions is beyond the scope of this document. If you would like to learn more, please read the technical documentation in the OpenAPI repository.
Structure
Addons augmenting Vanilla’s API v2 capabilities must have an openapi directory in the addon’s base directory. Inside this directory, there must be OpenAPI v3 YAML files, one for each resource. Each file should be named according to the resource it documents. For example, the directory for a Vanilla addon (“foo”), introducing an API v2 resource (“widgets”) would have the following structure:
foo
├── addon.json
├── FooPlugin.php
└── openapi
└── widgets.yml
The description of the “widgets” API v2 resource would be contained in widgets.yml and formatted to the OpenAPI v3 specification. For example, the description of a basic resource with a single get action might look like the following:
openapi: 3.0.2
paths:
"/widgets/{id}":
get:
parameters:
- description: "The widget ID"
in: path
name: id
required: true
schema:
type: integer
responses:
"200":
content:
"application/json":
schema:
properties:
addonID:
description: Unique ID for this widget.
type: number
title:
description: Name of the widget.
type: string
description: Success
tags:
- Widgets
summary: Get a single widget by its ID.
Updating Existing Resources
Vanilla generates its API v2 documentation by merging its endpoint descriptions. This means an addon can create a new parameter on an existing endpoint, or a new property on an existing schema, by using the existing items path. The result of the merge would contain the original description, in addition to new descriptors provided by the addon.
An addon that will include a new field (“widgetID”) on the core discussion resource schema could use the following OpenAPI v3 YAML file:
openapi: 3.0.2
components:
schemas:
Discussion:
properties:
widgetID:
description: Unique ID of the associated widget.
type: number
nullable: true
Special Considerations for OpenAPI v3 Validation
Vanilla attempts to generate valid OpenAPI v3 documentation based on files provided by its addons. The combined document must be valid per the OpenAPI v3 specification. However, the combined nature means each individual document may not need to be strictly valid. For example, the OpenAPI v3 specification requires valid info and paths keys. Since the generated document should already have an info key from core API documentation, addons likely do not need to provide their own. Similarly, some addons may only need to document new schemas and changes to existing schemas. In those cases, the paths key is not necessary and is already provided by core API documentation.
Developers preferring to utilize OpenAPI v3 validation tools while writing documentation can include empty keys for unused required fields as defined by the specification. These fields can be removed before the document is published or left in place. Empty keys should not adversely affect the final document generated by Vanilla.
