diff options
Diffstat (limited to 'api')
-rw-r--r-- | api/openapi-spec/blubberoid.yaml | 217 |
1 files changed, 217 insertions, 0 deletions
diff --git a/api/openapi-spec/blubberoid.yaml b/api/openapi-spec/blubberoid.yaml new file mode 100644 index 0000000..b0ee9ae --- /dev/null +++ b/api/openapi-spec/blubberoid.yaml @@ -0,0 +1,217 @@ +--- +openapi: '3.0.0' +info: + title: Blubberoid + description: > + Blubber is a highly opinionated abstraction for container build + configurations. + version: {{ .Version }} +paths: + /v1/{variant}: + post: + summary: > + Generates a valid Dockerfile based on Blubber YAML configuration + provided in the request body and the given variant name. + requestBody: + description: A valid Blubber configuration. + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/v3.Config' + application/yaml: + schema: + type: string + application/x-yaml: + schema: + type: string + responses: + '200': + description: OK. Response body should be a valid Dockerfile. + content: + text/plain: + schema: + type: string + '400': + description: Bad request. The YAML request body failed to parse. + '404': + description: No variant name was provided in the request path. + '422': + description: Provided Blubber config parsed correctly but failed validation. + '5XX': + description: An unexpected service-side error. + + x-amples: + - title: Mathoid test variant + request: + params: + variant: test + headers: + Content-Type: application/json + body: { + "version": "v3", + "base": "docker-registry.wikimedia.org/nodejs-slim", + "apt": { "packages": ["librsvg2-2"] }, + "lives": { "in": "/srv/service" }, + "variants": { + "build": { + "base": "docker-registry.wikimedia.org/nodejs-devel", + "apt": { + "packages": ["librsvg2-dev", "git", "pkg-config", "build-essential"] + }, + "node": { "requirements": ["package.json"] }, + "runs": { "environment": { "LINK": "g++" } } + }, + "test": { "includes": ["build"], "entrypoint": ["npm", "test"] } + } + } + response: + status: 200 + headers: + content-type: text/plain + body: /^FROM docker-registry.wikimedia.org\/nodejs-devel/ + +components: + schemas: + v3.Config: + title: Top-level blubber configuration (version v3) + allOf: + - $ref: '#/components/schemas/v3.CommonConfig' + - type: object + properties: + required: [version, variants] + version: + type: string + description: Blubber configuration version + variants: + type: object + description: Configuration variants (e.g. development, test, production) + additionalProperties: true + # OpenAPI 3.0 supports only v4 of the JSON Schema draft spec and + # cannot define schema for object properties with arbitrary + # names, but the following commented section is included to be + # useful to humans for the time being. It patiently awaits v6 + # json schema draft support before its uncommenting. + # + # patternProperties: + # "^[a-zA-Z][a-zA-Z0-9\-\.]+[a-zA-Z0-9]$": + # $ref: '#/components/schemas/v3.VariantConfig' + + v3.CommonConfig: + type: object + properties: + base: + type: string + description: Base image reference + apt: + type: object + properties: + packages: + type: array + description: Packages to install from APT sources of base image + items: + type: string + node: + type: object + properties: + env: + type: string + description: Node environment (e.g. production, etc.) + requirements: + type: array + description: Files needed for Node package installation (e.g. package.json, package-lock.json) + items: + type: string + python: + type: object + properties: + version: + type: string + description: Python binary present in the system (e.g. python3) + requirements: + type: array + description: Files needed for Python package installation (e.g. requirements.txt, etc.) + items: + type: string + builder: + type: object + properties: + command: + type: array + description: Command and arguments of an arbitrary build command + items: + type: string + requirements: + type: array + description: Files needed by the build command (e.g. Makefile, ./src/, etc.) + items: + type: string + lives: + type: object + properties: + as: + type: string + description: Owner (name) of application files within the container + uid: + type: integer + description: Owner (UID) of application files within the container + gid: + type: integer + description: Group owner (GID) of application files within the container + in: + type: string + description: Application working directory within the container + runs: + type: object + properties: + as: + type: string + description: Runtime process owner (name) of application entrypoint + uid: + type: integer + description: Runtime process owner (UID) of application entrypoint + gid: + type: integer + description: Runtime process group (GID) of application entrypoint + environment: + type: object + description: Environment variables and values to be set before entrypoint execution + additionalProperties: true + insecurely: + type: boolean + description: Skip dropping of priviledge to the runtime process owner before entrypoint execution + entrypoint: + type: array + description: Runtime entry point command and arguments + items: + type: string + v3.VariantConfig: + allOf: + - $ref: '#/components/schemas/v3.CommonConfig' + - type: object + properties: + includes: + type: array + description: Names of other variants to inherit configuration from + items: + description: Variant name + type: string + copies: + type: string + description: Name of variant from which to copy application files, resulting in a multi-stage build + artifacts: + type: array + items: + type: object + description: Artifacts to copy from another variant, resulting in a multi-stage build + required: [from, source, destination] + properties: + from: + type: string + description: Variant name + source: + type: string + description: Path of files/directories to copy + destination: + type: string + description: Destination path |