api-docs

API Documentation for Pilot Data Platform

Adding and Updating API Documentation

Structure

All API documentation is in the src/swagger/ folder. To update an existing API doc, simply overwrite one of the JSON files.

To add a new API doc, add the JSON file to the src/swagger/ folder, and update the index.js file to import the new JSON as well as update the dictionaries:

// Dictionary of imported specs
const specs = {
    ...
};

// Sidebar options that link to specs
const options = [
    ...
]

Retrieving API Docs from Services

From a running service you can curl the following:

curl localhost:<port>/openapi.json | jq . > <name_of_service>.json

Depending on the service, if it is built with Flask or FastAPI the path will be different in the curl command. swagger.json vs openapi.json

curl localhost:<port>/swagger.json | jq . > <name_of_service>.json

If you would like to pull the API documentation form a running instance in kubernetes and not have to run the service locally you can initiate a port forward to the service like so:

kubectl port-forward pods/<pod-name-of-service> <port>:<port> -n <namespace>

The service should then be available at localhost for the curl commands.

Run

npm i
npm start

Publish

npm run deploy