Generates JSDoc and SassDoc json for Origami components.
Running Origami Codedocs requires [Node.js] 14.x and [npm].
Before we can run the application, we'll need to install dependencies:
Run the application in development mode with:
npx serverless offline start
Now we can access the app over HTTP on port
We configure Origami CodeDocs using environment variables. In development, configurations are set in a
.env file. In production, these are set during deployment through CI config.
Configuration for Fastly is required in CI:
The following environment variables are also required in CI for a production deploy:
These production environment variables are mapped during a production deploy e.g.
AWS_ACCOUNT_ID is automatically set to the value of
AWS_ACCOUNT_ID_PROD. We do this as, at the time of writing, CI contexts are not available to users without root permissions.
Routes available include the following:
Routes for jsdoc:
Routes for sassdoc:
Routes for health:
componentId is the name and version of the component e.g.
To get JSDocs or SassDocs we must set the
x-api-key header, which is generated by Serverless when starting the application:
Serverless: Starting Offline: dev/eu-west-1. Serverless: Key with token: [your key here] Serverless: Remember to use x-api-key on the request headers
In a deployed environment these routes are prefixed with the "stage" either
x-api-key for a deployed service is available in Vault, or the latest may be found in AWS under "apigateway". This is an example request to the production service:
curl https://firstname.lastname@example.org -H "x-api-key:[key here]"
The tests are split into unit tests and integration tests. Unit tests are used for business logic, such as parsing a custom
@brand SassDoc parameter. Integration tests are used to test a deployed service end-to-end.
npm run test # run all the tests npm run test-unit # run the unit tests INTEGRATION_ENDPOINT=localhost:3000/dev npm run test-integration # run the integration tests against localhost (the service must be running locally first)
Integration tests run against the endpoint defined by the environment variable
INTEGRATION_ENDPOINT. If it is not configured the service endpoint defined in
.dev-stack.yml is used by default. This is generated automatically by serverless on deployment.
The code will also need to pass linting on CI, you can run the linter locally with:
npm run lint
CI will deploy the service on merge to the
master branch. It will first deploy to the development
dev environment to run integration tests. If tests pass it then deploys to the production
If you would like to deploy to the development
dev environment manually, run:
npx serverless deploy --stage dev --region eu-west-1
This is likely due to the Fastly API key expiring. Create a new personal api key in Fastly with access to the
origami-codedocs.in.ft.com service, and add this environment variable to CI.
If the service returns
403 "Forbidden" errors when running integration tests, it is likely the
CODEDOCS_API_KEY environment variable is incorrect.
CODEDOCS_API_KEY is set to the api key output by Serverless when running the app. For the
dev environment, make sure
CODEDOCS_API_KEY is set to the right value in CI. The api key of a deployed application can be found under "apigateway" in AWS.
Ensure the correct
x-api-key header is set when making requests. Locally the key is output by Serverless when running the app. The api key of a deployed application can be found under "apigateway" in AWS.
This software is published by the Financial Times under the MIT licence.