This repository holds the sources for the documentation of the REST API that was released in 1.7.
The API documentation can be found here: api.akeneo.com.
Install Docker Engine.
make buildThis is only building the documentation. The documentation is not available with this command, as it does not launch the HTTP server.
make watchThe REST API documentation site is then available on localhost:8000.
Files located in the content and src directories are watched for changes, so when developing you do not need to launch any other task.
To deploy the content of your PR, first merge your PR, and then trigger the CircleCI task continue_with_prod?.
NOTE: Once the "continue_with_prod?" task is completed, there is a delay before the new version of the documentation becomes visible.
In case you want to re deploy the Serenity documentation, look at the latest merge in master and click on Deployment.
Then click on Rerun.
As our YAML Swagger spec uses references and links, it is considered as non-valid.
During the build, we generate a valid JSON specification that is put under the content/swagger folder. Don't forget to version it if you made any change into the YAML Swagger spec.
Our Swagger spec is extended with custom properties:
| Property | Type | Description |
|---|---|---|
x-from-version |
string |
Indicates the version the property was added to the API. In the user documentation, hides the property from payload descriptions that doesn't match the selected API version. |
x-examples-per-version |
[Example object] | Allows to set a payload example for a specific version. Use as a Response object property. |
| Property | Type | Description |
|---|---|---|
x-version |
string |
API version of the example |
x-example |
any |
Example payload content |