This is a middleman site that accepts a Apia schema JSON file and an, optional, config YAML file and generates documentation as appropriate.
The best way to generate some docs is to use the Docker image. By default, it will:
- Export generated document to the
/outputdirectory - Read the schema from
/config/schema.json - Read configuration from
/config/config.yaml
You can specify the following environment variables to configure how docs are generated.
APIA_SCHEMA_URL- download the schema from the given URL rather than reading it from/config/schema.json.
The following options can be used to upload the generated output to a remote SSH/SFTP server.
UPLOAD_HOST- hostname to upload toUPLOAD_PORT- SSH port (defaults to 22)UPLOAD_USERNAME- the username to connect with (defaults to root)UPLOAD_PASSWORD- the password to autheticate withUPLOAD_KEY_PATH- a path to an passphrase-less SSH key within the container (you'll need to mount it)UPLOAD_PATH- the directory to upload the files to on the remote server
To build the image, you can simply use these commands:
make docker-image- builds the image locallymake docker-release- builds and releases the image
To develop locally, you can just run up the middleman server using the command below.
APIA_SCHEMA_PATH=examples/schemas/katapult.yaml bundle exec middleman server