peoray/api-docs

Notification management simplified.

The ultimate service for managing multi-channel notifications with a single API.

Explore the docs »

Report Bug · Request Feature · Join Our Discord · Roadmap · Twitter

API Documentation

This repository is the tool used to generate the API documentation using Gatsby static sites generator. The content is retrieved from Novu's API Swagger set in the API app, parsed and generated by Gatsby.

🚀 Getting Started

Local development

In order to run the API documentation generator locally you will need NPM installed in your local environment.

Then you firstly will install the project.

npm install

And then to run it.

npm start

Behind the scenes, the start script what it does is to call the develop script that runs Gatsby locally, executing the fetching of all the data, its parsing and generating the static content with the documentation for Novu's API.

For development purposes is recommended to set this environment variable located in ./.env (generated by copying ./.env.example.

GATSBY_NOVU_API_URL=http://localhost:3000
NOVU_API_URL=http://localhost:3000

You would need to set the value of the URL where your local development Novu API is being deployed. By default configuration Novu API is set to http://localhost:3000 but be aware that changing the default port values or where it is deployed will have a knock on effect for the API documentation generator here. GATSBY_NOVU_API_URL will render the proper URL in the content generated by Gatsby, allowing to quickly copy and paste the code examples generated for development use.

How it works?

Basically we fetch all the information from the Swagger endpoint of Novu API /api-json and that data is being parsed. There are two key things for the Swagger data to be able to be parsed. One is to define the tags for the different API resources. Second one is to add to the different public API endpoints that are going to be documented, the property summary with a short description of what the endpoint is for. Once the content is parsed and based on how it is defined in Swagger, Gatsby will generate the static content with the API endpoint definitions provided and some examples.