Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Show API documentation at /api/ #2650

Merged
merged 3 commits into from
Oct 23, 2023
Merged

Show API documentation at /api/ #2650

merged 3 commits into from
Oct 23, 2023

Conversation

mrkvon
Copy link
Contributor

@mrkvon mrkvon commented Oct 18, 2023

Proposed Changes

  • auto-generate API documentation in OpenAPI format with npm run generate-api-docs (the documentation isn't perfect, but it's good enough, much better than doing it manually) using swagger-autogen
  • display API documentation with Swagger-UI on /api/ path
  • hide the API documentation behind feature flag { featureFlags: { apidocs: true } } in ./config/env/local.js
    • by default it shows in development, but not in production
  • generate up-to-date documentation before every commit with husky
  • additional fix: update leaflet-active-area library to latest version from npm; otherwise webhooks fail to install node_modules when they try to fetch the library from github, because of some weird ssh authentication reason.

The OpenAPI json, and files for Swagger-UI are stored in /apidocs/ folder. It can be moved elsewhere if somebody prefers

Motivation

For people who want to develop e.g. mobile app on top of Trustroots API, this can be useful resource

Testing instructions

  1. Update node_modules by running npm ci

  2. Try to delete /apidocs/openapi.json, then run npm run generate-api-docs, and it should re-appear

  3. Run the app locally, and go to http://localhost:3000/api/, and you should see
    image

  4. If running the whole app locally is too much for you, you can

  • install e.g. http-server: sudo npm install -g http-server
  • in terminal, go to Trustroots repository that you cloned locally
  • go to this branch git switch api-docs
  • cd apidocs/
  • run the server with command http-server
  • in your browser, go to http://localhost:8080, and see the documentation

mrkvon added 2 commits October 18, 2023 03:12
It is shown in development, but not in production
and can be turned on/off with config.featureFlags.apidocs

Generated with swagger-autogen
Displayed with Swagger-UI v5.9.0
https://github.com/swagger-api/swagger-ui

The documentation gets updated in pre-commit hook
@mrkvon mrkvon changed the title Generate API docs Show API documentation at /api/ Oct 18, 2023
to get rid of workflows error
@JohnvdWaeter
Copy link
Contributor

Tried it locally, looks fine to me (although I have no idea what I should see :) )

@mrkvon
Copy link
Contributor Author

mrkvon commented Oct 18, 2023

Tried it locally, looks fine to me (although I have no idea what I should see :) )

If you go to http://localhost:3000/api/, you should be able to see the Swagger documentation of Trustroots API

@JohnvdWaeter
Copy link
Contributor

Yes, that works!

@mrkvon
Copy link
Contributor Author

mrkvon commented Oct 19, 2023

Ok, great! Thank you for testing @JohnvdWaeter!
I'd like to give @robokow opportunity to deploy #2649 separately, and when that one is in production, let's merge this one. Please, @robokow ping me here when you deploy #2649. Thanks!

@mrkvon mrkvon merged commit 0153076 into master Oct 23, 2023
4 checks passed
@mrkvon mrkvon deleted the api-docs branch October 23, 2023 20:57
@mrkvon
Copy link
Contributor Author

mrkvon commented Oct 23, 2023

Proceeding with the merge, since b7b9725 was deployed. ✅

mrkvon added a commit that referenced this pull request Jan 16, 2024
It is shown in development, but not in production
and can be turned on/off with config.featureFlags.apidocs

Generated with swagger-autogen https://www.npmjs.com/package/swagger-autogen
Displayed with Swagger-UI v5.9.0 https://github.com/swagger-api/swagger-ui

The documentation gets updated in pre-commit hook
chmac added a commit that referenced this pull request Jan 25, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants