Swagger Documentation

Chatwoot maintains its API documentation using swagger. Therefore, whenever you commit an API change to Chatwoot, The associated swagger Documentation needs to be updated.

This guide will walk you through adding documentation for a new endpoint in Chatwoot's swagger.json. The guide uses Canned Responses as the example object for documentation.

Prerequisities

You can access swagger documentation for the Chatwoot app in your local installation over: http://localhost:3000/swagger The commands to update your swagger.json is as follows.

rake swagger:build

If you are familiar with the process, need a sample reference, head over to the example Pull Request

Steps to add a new endpoint

1. Define Tag in swagger index

Define the Tag for the object to be added in swagger/index.yml. Since we want this endpoint under Application APIs, it is added under the name Application.

see the changes in reference commit

2. Add the resource definition

Add the resource definition and its attributes to a definition file. You should place the resource definition file in the root or a sub folder of swagger/definitions/resource.

Don't forget to add the resource definition path to index in swagger/definitions/index.yml In our case for the Canned Response, we are placing it in swagger/definitions/resource/canned_response.yml

see the changes in reference commit

3. Define request payloads

The next step is to define the request payloads. You can split methods like create, update etc. into single or multiple files based on your requirement. Also, make sure to add the paths to the index.

Ensure to add the response payload definition path to index in swagger/definitions/index.yml

In our case of Canned Response, since the payload is the same for both create and update, we are adding it in swagger/definitions/request/canned_response/create_update_payload.yml

see the changes in reference commit

4. Define request paths

Define the required paths for the endpoint to swagger/paths/index.yml. Create appropriate files for each route. In the path definitions, you can reference the request objects defined in step 2 and params from step 3.

For Canned Response, we are defining the following path files.

swagger/paths/application/canned_responses/create.yml
swagger/paths/application/canned_responses/delete.yml
swagger/paths/application/canned_responses/index.yml
swagger/paths/application/canned_responses/update.yml

see the changes in reference commit

5. Build and verify

Run rake swagger:build and verify the updated documentation at http://localhost:3000/swagger. If there are build errors, you will see them while loading the documentation in the browser. Fix the issues and re-run build until the documentation is ready. Then, raise a PR with the changes.

Ensure to commit the newly generated /swagger/swagger.json.

see the changes in reference commit

Updating Chatwoot API docs page

If you are a community contributor, The PR reviewer will take care of this step.

Updating the swagger documentation on https://www.chatwoot.com/developers/api/ requires a commit on the chatwoot-website repo.

You should copy the contents of newly generated swagger.json and update the following files in the chatwoot-website repo

src/data/swagger/swagger-develop.json
src/data/swagger/swagger.json

see the changes in reference pull request