API documentation info

You can view Teletraan's API documentation in two ways:

1. Through generated .md files in the docs/api directory.

2. Through Swagger-UI with deploy-board and deploy-service running: http://your-deploy-board-url/api-docs

Note: You will need to specify your Teletraan server url in the first field with /swagger.json appended. If you have authentication and/or authorization enabled you will need to provide your token in the second field as well.

Generating new markdown documentation

Teletraan uses Swagger to document its RESTful API. We have included Swagger2Markup to generate new API docs from the swagger.json output should you make some changes!

Note: You need Python installed to run the generation script.

0. Make sure the application is up and running. Such as

teletraan$ docker-compose -f docker-compose.yml up

1. Go to the docs_generator directory.

$ cd teletraan/docs/docs_generator

2. Build Swagger2Markup.

$ ./gradlew build

3. Run the docs generation script. Teletraan server will need to be running and you will want to include the url to the swagger.json file. This is found by appending /swagger.json to the url of your teletraan server (example: http://localhost:8080/swagger.json).

$ python generate_api_docs.py http://localhost:8080/swagger.json

This will generate the new docs under the docs/api directory directory.