This repository is used to generate inventaire's API, inventaire.io API documentation. The documentation UI is based on Swagger UI.
Until we find an elegant way to generate the documentation automatically, the API documentation is being maintained manually. For this reason, it is currently often out-of-date. Your help to maintain it up-to-date is thus very welcome. To contribute to this effort, you can follow those steps:
- Fork the repository inventaire/inventaire-api.
- Update the documentation: you just need to create, modify or delete files in the
inv-specdirectory. - Share your changes by submitting a pull request.
To view the documentation locally you need NodeJS v8 and an HTTP file server, or Docker.
- If you installed Node with nvm, you can temporarly (just for the present terminal session) switch to NodeJS v8 by running
nvm use 8 - Install the dependencies:
npm install - Build the documentation:
npm run build - Start the file server:
npm run start
- To update the documentation UI:
npm run build - To update just the API specs:
npm run update-spec - To update just the API specs on every file change:
npm run watch-spec
If you don't want to install NodeJS on your machine, you can use it in a Docker container
- Install the dependencies:
docker run -it --rm -u 'node' -v $(pwd):/data -w /data node:8 npm install - Build the documentation:
docker run -it --rm -v $(pwd):/data -w /data node:8 npm run build - Launch a file web server:
cd dist && python -m SimpleHTTPServer - Access the documentation through your browser at http://localhost:8080.
- To update the UI:
docker run -it --rm -v $(pwd):/data -w /data node:8 npm run build - To update the API specs alone:
docker run -it --rm -v $(pwd):/data -w /data node:8 npm run update-spec - To delete the generated documentation:
rm -rf ./dist