This repository holds the specification for the Giant Swarm API, starting at version v4
.
The specs are written in the OpenAPI v2.0 format, formerly known as Swagger.
The specification YAML files are:
spec.yaml
- main specification filedefinitions.yaml
- definition of models for request and response bodiesparameters.yaml
- definition of parameters used in paths and headersresponses.yaml
- re-usable response specs
We host a browser-friendly version at https://docs.giantswarm.io/api/
That documentation is a rendition of the specification of the master
branch of this repository.
See the details
folder of this repo for additional content about the API.
As usual, collaboration on this spec is done based on feature branches and pull requests.
Feature branches shall be merged into master
only when the API functionality they describe is implemented and available to users of the Giant Swarm API.
Hidden operations
Some API operations contained in the spec are not yet usable, yet we want to have them in the spec already. These operations are marked using the x-internal: true
attribute and filtered out before rendering the documentation.
- Attribute names use only lowercase letters and the underscore as a seperator, like
attribute_name
. - Paths/routes have a trailing slash (
/path/
instead of/path
) - Time data is given in the form
"2000-01-01T12:00:00.000Z"
. The number of decimal places for the seconds component may vary.
Please obey these conventions when editing the spec YAML files:
- Indent using spaces, not tabs
- 2 spaces per indentation level
- avoid quotes where possible
Run make validate
to check the YAML integrity as well as the validity of the OpenAPI spec.
Use this command from the root directory of your clone of this repo:
make run-server
Then open http://localhost:8080/
to access your specs displayed via ReDoc.
make mock
Then access http://localhost:4010
as your endpoint. E. g. gsctl -e http://localhost:4010 list clusters
.
Alternatively, you can run make mock-dynamic
to let the mock server respond with dynamically generated fake data.