api.stackstorm.com is unsync with openapi.yaml (CD)

[nmaludy]

In the openapi spec there are several instances of a block called x-parameters. These are "vendor extensions" according the OpenAPI spec https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#patterned-objects .

The API documentation generator is leaving these out, so there's no way to know they exist without looking directly at the spec.

Example:

• API docs for POST /auth/v1/tokens https://api.stackstorm.com/auth/v1/tokens/#/token_controller.post
• Spec for POST /auth/v1/tokens https://github.com/StackStorm/st2/blob/master/st2common/st2common/openapi.yaml#L3991-L4020
• You can see that the parameters remote_addr and remote_user are missing from the docus, even though they're in the spec.

[arm4b]

Confirming there is unsync between https://api.stackstorm.com/ and openapi.yaml.

After looking further, last update for https://api.stackstorm.com is Nov 3, 2017, according to #4046 (comment).

---

We'll need to add re-generation task for api.stackstorm.com in CircleCI if openapi.yaml content was changed (on master build, similar to deploy job).

[lakshmi-kannan]

@enykeev and I had a chat and we decided on the following:

1. We'll ship updated documentation on every release. Having API documentation from master is a stretch goal. We can use api-unstable.stackstorm.com for this if needed.

In terms of how we are going to automate this:

1. We are going to add a task in st2cd release automation to invoke a circle build on https://github.com/StackStorm/st2apidocs

There are some minor improvements we decided to do. I'll link PRs here when I make those changes.

[lakshmi-kannan]

Some changes to st2apidocs to ship stable and unstable API docs separately StackStorm/st2apidocs#3
Release automation to kick off Circle CI build in st2apidocs https://github.com/StackStorm/st2cd/pull/325/files

[lakshmi-kannan]

Also, I created api-unstable.stackstorm.com to show master API documentation. When DNS propagates, this should work.

[arm4b]

https://github.com/StackStorm/st2apidocs is responsible for the https://api.stackstorm.com/ generation.

Looks like the build in https://github.com/StackStorm/st2apidocs is still broken that results in CD failure to generate and upload the documentation. See StackStorm/st2apidocs#9 for more info.