Documenting Endpoints

Documenting Endpoints

All available API v2 endpoints must appear on the API v2 page in the Vanilla dashboard. Addons augumenting Vanilla’s API v2 capabilities must include valid OpenAPI v3 documentation to describe those changes.

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 stricly 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.

Cloud Hosting

We believe that online communities should be intuitive, engaging and true to your brand. Vanilla allows you to create a customized community that rewards positive participation, automatically curates content and lets members drive moderation.

Learn More …