Provide OpenAPI spec for Blubberoid

Wrote an OpenAPI 3.0 spec for Blubberoid that provides `x-amples`
entries compatible with service-checker.

The written spec includes basic schema for Blubber config objects that
may be later factored out for use in validation.

Note that OpenAPI 3.0 supports only the v4 draft of the JSON Schema
standard, so some parts of the configuration could not be fully
described. Specifically, v4 does not include the `patternProperties`
definition introduced in the JSON Schema v6 draft that would allow us to
describe `variants` and `runs.environment` and everything beneath.

Blubberoid was refactored slightly to incorporate the new spec as well
as assume JSON as the canonical and default configuration format. It was
also refactored to include a versioned namespace ("v1") after the server
endpoint.

Bug: T205920
Change-Id: I28a341aa503b8920d802715660d4c4d62be45475

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