Wv 102 merge https docs.seqera.io wave api into openapi

typespec/models/BuildStatusResponse.tsp

@@ -1,6 +1,14 @@
 import "./Status.tsp";
 
 @doc("Response payload for build status.")
+@example(#{
+    id:"6c084f2e43f86a78_1",
+    status:Status.COMPLETED,
+    startTime:"2024-04-09T20:31:35.355423Z",
+    duration: "123.914989000",
+    succeeded: true
+}
+)
 model BuildStatusResponse {
   duration: string;
   id: string;

typespec/models/CondaOpts.tsp

@@ -1,6 +1,14 @@
 @doc("Options for Conda environments.")
+@example(#{
+    basePackages: "python=3.8",
+    commands: #["pip install bwa", "pip install salmon"],
+    mambaImage: "mambaorg/micromamba:0.15.3"
+})
 model CondaOpts {
+  @doc("Names of base packages.")
   basePackages: string;
+  @doc("Command to be included in the container.")
   commands: string[];
+  @doc("Name of the docker image used to build Conda containers.")
   mambaImage: string;
-}
+}

typespec/models/CondaPackages.tsp

@@ -0,0 +1,14 @@
+import "./CondaOpts.tsp";
+
+@doc("Package configurations for container builds.")
+model CondaPackages {
+  @doc("Conda channels to search for packages.")
+  channels: string[];
+  condaOpts?: CondaOpts;
+  @doc("Conda packages to install.")
+  entries: string[];
+  @doc("The package environment file encoded as a base64 string.")
+  environment?: string;
+  @doc("This represents the type of package builder. Use `CONDA`.")
+  type: "CONDA";
+}

typespec/models/ContainerConfig.tsp

@@ -1,10 +1,29 @@
 import "./ContainerLayer.tsp";
 
 @doc("Configuration details for a container.")
+@example(#{
+    cmd: #["echo", "hello"],
+    entrypoint: #["/bin/sh"],
+    env: #["FOO=bar"],
+    layers: #[
+      #{
+        gzipDigest: "sha256:1234567890abcdef",
+        gzipSize: "1234",
+        location: "https://seqera.io/layer.tar.gz",
+        skipHashing: false,
+        tarDigest: "sha256:abcdef1234567890"
+      }
+      ],
+      workingDir: "/app"
+})
 model ContainerConfig {
+  @doc("The launch command to be used by the Wave container, e.g., `['echo', 'Hello world']` (optional).")
   cmd: string[];
+  @doc("The container entrypoint command, e.g., `['/bin/bash']`.")
   entrypoint: string[];
+  @doc("The environment variables to be defined in the Wave container, e.g., `['FOO=one','BAR=two']` (optional).")
   env: string[];
   layers: ContainerLayer[];
+  @doc("The work directory to be used in the Wave container, e.g., `/some/work/dir` (optional).")
   workingDir: string;
 }

typespec/models/ContainerInspectConfig.tsp

@@ -1,7 +1,25 @@
 import "./RootFS.tsp";
 
 @doc("Configuration details of a container.")
-model Config {
+@example(#{
+    architecture: "linux/amd64",
+    config: #{
+    attachStdin: false,
+    attachStdout: true,
+    attachStderr: true,
+    tty: false,
+    env: #["PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"],
+    cmd: #["sh"],
+    image: "alpine:latest"
+    },
+    container: "docker.io/alpine:latest",
+    created: "2021-06-10T15:00:00.000000000Z",
+    rootfs: #{
+        diff_ids: #["sha256:1234567890abcdef"],
+        type: "layers"
+    }
+})
+model ContainerInspectConfig {
   architecture: string;
   config: {
     attachStdin: boolean;
@@ -15,4 +33,4 @@ model Config {
   container: string;
   created: string;
   rootfs: RootFS;
-}
+}

typespec/models/ContainerInspectRequest.tsp

@@ -1,7 +1,17 @@
 @doc("Request payload for inspecting a container.")
+@example(#{
+    containerImage: "docker.io/alpine:latest",
+    towerAccessToken: "1234567890abcdef",
+    towerEndpoint: "https://api.cloud.seqera.io",
+    towerWorkspaceId: 1234567890
+})
 model ContainerInspectRequest {
+  @doc("Name of the container to be inpected, e.g., `docker.io/library/ubuntu:latest`")
   containerImage: string;
+  @doc("Access token of the user account granting the access to the Seqera Platform service specified via `towerEndpoint` (optional).  ")
   towerAccessToken: string;
+  @doc("Seqera Platform service endpoint from where container registry credentials are retrieved (optional). Default `https://api.cloud.seqera.io`. ")
   towerEndpoint: string;
+  @doc("ID of the Seqera Platform workspace from where the container registry credentials are retrieved (optional). When omitted the personal workspace is used.")
   towerWorkspaceId: int64;
-}
+}

typespec/models/ContainerInspectResponse.tsp

@@ -2,14 +2,60 @@ import "./ContainerInspectConfig.tsp";
 import "./Manifest.tsp";
 
 @doc("Response payload for inspecting a container.")
+@example(#{
+ Container: #{
+  registry: "docker.io",
+  hostName: "docker.io",
+  imageName: "alpine",
+  reference: "latest",
+  digest: "sha256:1234567890abcdef",
+  config: #{
+   architecture: "linux/amd64",
+   config: #{
+    attachStdin: false,
+    attachStdout: true,
+    attachStderr: true,
+    tty: false,
+    env: #["PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"],
+    cmd: #["sh"],
+    image: "alpine:latest"
+   },
+   container: "docker.io/alpine:latest",
+   created: "2021-06-10T15:00:00.000000000Z",
+   rootfs: #{
+    diff_ids: #["sha256:1234567890abcdef"],
+    type: "layers"
+   }
+  },
+  manifest: #{
+   schemaVersion: 2,
+   mediaType: "application/vnd.docker.distribution.manifest.v2+json",
+   config: #{
+    mediaType: "application/vnd.docker.container.image.v1+json",
+    size: 123456,
+    digest: "sha256:1234567890abcdef"
+   },
+   layers: #[
+    #{
+     mediaType: "application/vnd.docker.image.rootfs.diff.tar.gzip",
+     size: 123456,
+     digest: "sha256:1234567890abcdef"
+    }
+   ]
+  },
+  v1: false,
+  v2: true,
+  oci: false
+ }
+})
 model ContainerInspectResponse {
  Container: {
   registry: string;
   hostName: string;
   imageName: string;
   reference: string;
   digest: string;
-  config: Config;
+  config: ContainerInspectConfig;
   manifest: Manifest;
   v1: boolean;
   v2: boolean;

typespec/models/ContainerLayer.tsp

@@ -1,8 +1,20 @@
 @doc("Represents a layer in a container image.")
+@example(#{
+  gzipDigest: "sha256:1234567890abcdef",
+  gzipSize: "123456",
+  location: "https://example.com/image.tar.gz",
+  skipHashing: false,
+  tarDigest: "sha256:abcdef1234567890"
+})
 model ContainerLayer {
+  @doc("The SHA256 checksum of the provided layer tar gzip file, e.g., `sha256:a7c724b02...`.")
   gzipDigest: string;
+  @doc("The size in bytes of the the provided layer tar gzip file.")
   gzipSize: string;
+  @doc("Specifies a container image layer stored as a tar.gz file (optional). Either a HTTP URL to the file or a base64 encoded string prefixed with `data:`.")
   location: string;
+  @doc("If true, the layer tar file will not be hashed.")
   skipHashing: boolean;
+  @doc("The SHA256checksum of the provided tar file, e.g., `sha256:a7c724b02...`.")
   tarDigest: string;
 }

typespec/models/ContainerMirrorResponse.tsp

@@ -2,6 +2,22 @@ import "./ContainerPlatform.tsp";
 import "./Status.tsp";
 
 @doc("Response payload for container mirroring.")
+@example(#{
+    mirrorId: "6c084f2e43f86a78_1",
+    digest: "sha256:1234567890abcdef",
+    sourceImage: "docker.io/alpine:latest",
+    targetImage: "docker.io/alpine:latest",
+    platform: #{
+                os: "LINUX",
+                arch: "AMD64",
+                variant: "v1"
+              },
+    creationTime: "2024-04-09T20:31:35.355423Z",
+    status: Status.COMPLETED,
+    duration: "123.914989000",
+    exitCode: 0,
+    logs: "Successfully mirrored image."
+})
 model ContainerMirrorResponse {
   mirrorId: string;
   digest: string;

typespec/models/ContainerPlatform.tsp

@@ -1,4 +1,9 @@
 @doc("Represents os platform of a container.")
+@example(#{
+  os: "linux",
+  arch: "amd64",
+  variant: "v1"
+})
 model ContainerPlatform {
   os: string;
   arch: string;

typespec/models/ContainerRequest.tsp

@@ -1,31 +1,58 @@
 import "./ContainerConfig.tsp";
-import "./Packages.tsp";
+import "./CondaPackages.tsp";
 import "./ScanMode.tsp";
 import "./ScanLevel.tsp";
 
 @doc("Request payload for creating a container token.")
+@example(#{
+    packages:#{
+            type: "CONDA",
+            entries: #["salmon", "bwa"],
+            channels: #["conda-forge", "bioconda"]
+        },
+        format: "docker",
+        containerPlatform:"linux/amd64"
+})
 model ContainerRequest {
-  buildContext: ContainerLayer;
+  buildContext?: ContainerLayer;
+  @doc("Container repository where container builds should be pushed, e.g., `docker.io/user/my-image` (optional).")
   buildRepository?: string;
+  @doc("Container repository used to cache build layers `docker.io/user/my-cache` (optional).")
   cacheRepository?: string;
-  containerConfig: ContainerConfig;
+  containerConfig?: ContainerConfig;
+  @doc("Dockerfile used for building a new container encoded in base64 (optional). When provided, the attribute `containerImage` must be omitted.")
   containerFile?: string;
-  containerImage: string;
-  containerIncludes: string[];
+  @doc("Name of the container to be served, e.g., `docker.io/library/ubuntu:latest` (optional). If omitted, the `containerFile` must be provided.  ")
+  containerImage?: string;
+  @doc("List of container images to include in the built container (optional).")
+  containerIncludes?: string[];
+  @doc("Target container architecture of the built container, e.g., `linux/amd64` (optional). Currently only supporting amd64 and arm64.")
   containerPlatform: string;
-  dryRun: boolean;
+  @doc("Request to build the container in a dry-run mode.")
+  dryRun?: boolean;
+  @doc("Request unique fingerprint.")
   fingerprint?: string;
+  @doc("The format of the container to be built. Its values can be `sif` for singularity or `docker` as default. ")
   format: "sif" | "docker";
+  @doc("Freeze requires buildRepository to push the build container to a user-defined repository. This provides the container URL from the user-defined repository, not the Wave generated URL. This URL won't change.")
   freeze?: boolean;
+  @doc("The name strategy to be used to create the name of the container built by Wave. Its values can be `none`, `tagPrefix`, or `imageSuffix`. ")
   nameStrategy?: "none" | "tagPrefix" | "imageSuffix";
   mirror?: boolean;
-  packages?: Packages;
+  @doc("Conda packages to be installed in the container.")
+  packages?: CondaPackages;
   scanMode?: ScanMode;
   scanLevels?: ScanLevel[];
-  timestamp: string;
+  @doc("Request submission timestamp using ISO-8601.")
+  timestamp?: string;
+  @doc("Access token of the user account granting access to the Seqera Platform service specified via `towerEndpoint` (optional).")
   towerAccessToken?: string;
+  @doc("Seqera Platform service endpoint from where container registry credentials are retrieved (optional). Default `https://api.cloud.seqera.io`.")
   towerEndpoint?: string;
+  @doc("Token to refresh ``towerAccessToken` after it become invalid (optional).")
   towerRefreshToken?: string;
-  towerWorkspaceId?: int32;
-  workflowId: string;
+  @doc("ID of the Seqera Platform workspace from where the container registry credentials are retrieved (optional). When omitted the personal workspace is used.")
+  towerWorkspaceId?: int64;
+  @doc("ID of the Seqera Platform workspace from which this container request originates (optional).")
+  workflowId?: string;
 }

typespec/models/ContainerResponse.tsp

@@ -1,16 +1,40 @@
 import "./ContainerStatus.tsp";
 
 @doc("Response payload for container token creation.")
+@example(#{
+    containerToken:"732b73aa17c8",
+    targetImage:"wave.seqera.io/wt/732b73aa17c8/build/dev:salmon_bwa--5e49881e6ad74121",
+    expiration:"2024-04-09T21:19:01.715321Z",
+    buildId:"5e49881e6ad74121_1",
+    cached:false,
+    freeze:false,
+    mirror:false,
+    requestId:"5e49881e6ad74121",
+    scanId:"5e49881e6ad74121",
+    containerImage:"docker.io/build/dev:salmon_bwa--5e49881e6ad74121",
+    status:ContainerStatus.PENDING
+    })
 model ContainerResponse {
+  @doc("Unique identifier for the build.")
   buildId: string;
+  @doc("Indicates if the build is cached.")
   cached: boolean;
+  @doc("Container image to be used.")
   containerImage: string;
+  @doc("Token to access the container.")
   containerToken: string;
+  @doc("The expiration timestamp of the Wave container using ISO-8601 format.")
   expiration: string;
+  @doc("Indicates if the build is pushed to user container registry.")
   freeze: boolean;
+  @doc("Indicates if its a mirror request.")
   mirror: boolean;
+  @doc("Unique identifier for the request.")
   requestId: string;
+  @doc("Unique identifier for the scan.")
   scanId: string;
+  @doc("Status of the container build.")
   status: ContainerStatus;
+  @doc("The Wave container image name")
   targetImage: string;
 }

typespec/models/ContainerStatusResponse.tsp

@@ -1,15 +1,25 @@
 import "./ContainerStatus.tsp";
 
 @doc("Response payload for container status.")
+@example(#{
+    id:"6c084f2e43f86a78",
+    buildId:"6c084f2e43f86a78_1",
+    status:ContainerStatus.DONE,
+    creationTime:"2024-04-09T20:31:35.355423Z",
+    detailsUri:"https://wave.seqera.io/view/builds/6c084f2e43f86a78_1",
+    duration:"123.914989000",
+    succeeded:true,
+    scanId:"6c084f2e43f86a78_1",
+})
 model ContainerStatusResponse {
   id: string;
   status: ContainerStatus;
   buildId: string;
-  mirrorId: string;
+  mirrorId?: string;
   scanId: string;
-  vulnerabilities: Record<vulnerability>;
+  vulnerabilities?: Record<vulnerability>;
   succeeded: boolean;
-  reason: string;
+  reason?: string;
   detailsUri: string;
   creationTime: string;
   duration: string;