Openapi v3 docs parity

docs/openapi/.redocly.lint-ignore.yaml

@@ -1,5 +1,2 @@
 # This file instructs Redocly's linter to ignore the rules contained for specific parts of your API.
 # See https://redocly.com/docs/cli/ for more information.
-apis/cf/latest/paths/Packages.yaml:
-  operation-2xx-response:
-    - '#/~1v3~1packages~1{guid}~1download/get/responses'

docs/openapi/apis/cf/latest/components/requestBodies/AppCreateRequestBody.yaml

@@ -7,25 +7,31 @@ content:
       properties:
         name:
           type: string
-          description: Name of the app
-        environment_variables:
-          type: object
-          description: Environment variables to be used for the App when running
-          additionalProperties:
-            type: string
-        lifecycle:
-          $ref: ../schemas/Lifecycle.yaml
-          description: Provides the lifecycle object for the application
+          description: Name of the app; must be unique within the space (case-insensitive)
         relationships:
           type: object
+          description: Relationships to other resources
           properties:
             space:
               $ref: ../schemas/RelationshipToOne.yaml
               description: A relationship to a space
           required:
             - space
+        environment_variables:
+          type: object
+          description: Environment variables to be used for the App when running
+          default: {}
+          additionalProperties:
+            type: string
+        lifecycle:
+          $ref: ../schemas/Lifecycle.yaml
+          description: Provides the lifecycle object for the application; defaults to the [buildpack lifecycle](#buildpack-lifecycle-object)
         metadata:
           $ref: ../schemas/Metadata.yaml
+          description: |-
+            `labels`: Labels applied to the app
+
+            `annotations`: Annotations applied to the app
       required:
         - name
         - relationships
@@ -38,4 +44,4 @@ content:
           relationships:
             space:
               data:
-                guid: 123e4567-e89b-12d3-a456-426614174000
+                guid: 2f35885d-0c9d-4423-83ad-fd05066f8576

docs/openapi/apis/cf/latest/components/requestBodies/AppUpdateRequestBody.yaml

@@ -8,16 +8,15 @@ content:
         name:
           type: string
           description: Name of the app
-        environment_variables:
-          type: object
-          description: Environment variables to be used for the App when running
-          additionalProperties:
-            type: string
         lifecycle:
           $ref: ../schemas/Lifecycle.yaml
-          description: Lifecycle to be used when updating the app; note `data` is a required field in lifecycle if lifecycle is updated. `type` may NOT be changed from its current value.
+          description: 'Lifecycle to be used when updating the app; note: `data` is a required field in lifecycle if lifecycle is updated. `type` may NOT be changed from its current value.'
         metadata:
           $ref: ../schemas/Metadata.yaml
+          description: |-
+            `labels`: Labels applied to the app
+
+            `annotations`: Annotations applied to the app
       description: Request schema for updating an app
     examples:
       default:

docs/openapi/apis/cf/latest/components/requestBodies/BuildCreateRequestBody.yaml

@@ -11,14 +11,31 @@ content:
             guid:
               type: string
               format: uuid
+              description: The guid of the app package to stage
           required:
             - guid
           description: App package to stage
         lifecycle:
           $ref: '../schemas/Lifecycle.yaml'
-          description: Lifecycle information for a build
+          description: Lifecycle information for a build; defaults to the lifecycle on the app
+        staging_memory_in_mb:
+          type: integer
+          description: Memory in MB allocated for staging of the build
+        staging_disk_in_mb:
+          type: integer
+          description: Disk space in MB allocated for staging of the build
+        staging_log_rate_limit_bytes_per_second:
+          type: integer
+          description: Log rate limit in bytes per second allocated for staging of the build
         metadata:
           $ref: '../schemas/Metadata.yaml'
+          description: Labels and annotations applied to the build
       required:
         - package
       description: Request schema for creating a build
+    examples:
+      default:
+        summary: default
+        value:
+          package:
+            guid: 8e4da443-f255-499c-8b47-b3729b5b7432

docs/openapi/apis/cf/latest/components/requestBodies/BuildpackCreateRequestBody.yaml

@@ -7,24 +7,36 @@ content:
       properties:
         name:
           type: string
-          description: The name of the buildpack
+          description: Name of the buildpack; must be unique per stack (case-sensitive)
         stack:
-          type: string
+          type: [string, 'null']
+          default: null
           description: The name of the stack that the buildpack will use
         position:
           type: integer
+          default: 1
           description: The order in which the buildpacks are checked during buildpack auto-detection
         lifecycle:
           type: string
+          default: buildpack
+          enum:
+            - buildpack
+            - cnb
           description: The version of buildpack the buildpack will use. `buildpack` indicates [Classic Buildpacks](https://docs.cloudfoundry.org/buildpacks/classic.html). `cnb` indicates [Cloud Native Buildpacks](https://docs.cloudfoundry.org/buildpacks/cnb/)
         enabled:
           type: boolean
+          default: true
           description: Whether or not the buildpack will be used for staging
         locked:
           type: boolean
+          default: false
           description: Whether or not the buildpack is locked to prevent updating the bits
         metadata:
           $ref: ../schemas/Metadata.yaml
+          description: |-
+            `labels`: Labels applied to the buildpack
+
+            `annotations`: Annotations applied to the buildpack
       required:
         - name
       description: Request schema for creating a buildpack

docs/openapi/apis/cf/latest/components/requestBodies/BuildpackUpdateRequestBody.yaml

@@ -7,7 +7,10 @@ content:
       properties:
         name:
           type: string
-          description: The name of the buildpack
+          description: Name of the buildpack
+        stack:
+          type: [string, 'null']
+          description: The name of the stack that the buildpack will use
         position:
           type: integer
           description: The order in which the buildpacks are checked during buildpack auto-detection
@@ -17,11 +20,12 @@ content:
         locked:
           type: boolean
           description: Whether or not the buildpack is locked to prevent updating the bits
-        stack:
-          type: string
-          description: The name of the stack that the buildpack will use
         metadata:
           $ref: ../schemas/Metadata.yaml
+          description: |-
+            `labels`: Labels applied to the buildpack
+
+            `annotations`: Annotations applied to the buildpack
       description: Request schema for updating a buildpack
     examples:
       default:

docs/openapi/apis/cf/latest/components/requestBodies/DomainCreateRequestBody.yaml

@@ -9,31 +9,53 @@ content:
       properties:
         name:
           type: string
-          description: Name of the domain
+          description: Name of the domain; must be unique (case-insensitive)
         internal:
           type: boolean
-          description: Whether the domain is used for internal (container-to-container) traffic
+          default: false
+          description: Whether the domain is used for internal (container-to-container) traffic, or external (user-to-container) traffic
         router_group:
           type: object
           properties:
             guid:
               type: string
               format: uuid
-          description: 'The desired router group guid.  _note: creates a `tcp` domain; cannot be used when `internal` is set to `true` or domain is scoped to an org_'
+              description: The desired router group guid
+          description: 'The desired router group. _note: creates a `tcp` domain; cannot be used when `internal` is set to `true` or domain is scoped to an org_'
+        enforce_route_policies:
+          type: boolean
+          default: false
+          description: When `true`, GoRouter enforces route policies for routes on this domain using mutual TLS (mTLS). Set at creation only; cannot be changed on update. Cannot be used with internal domains
+        route_policies_scope:
+          type: string
+          enum:
+            - any
+            - org
+            - space
+          description: 'Operator-defined boundary for allowed callers: `any`, `org`, or `space`. Required when `enforce_route_policies` is `true`. Set at creation only; cannot be changed on update'
         relationships:
           type: object
           properties:
             organization:
               $ref: ../schemas/RelationshipToOne.yaml
-              description: A relationship to the organization the domain will be scoped to;  _note cannot be used when `internal` is set to `true` or domain is associated with a router group_
+              description: 'A relationship to the organization the domain will be scoped to; _note: cannot be used when `internal` is set to `true` or domain is associated with a router group_'
             shared_organizations:
               $ref: ../schemas/RelationshipToMany.yaml
-              description: A relationship to organizations the domain will be shared with  _Note cannot be used without an organization relationship_
+              description: 'A relationship to organizations the domain will be shared with. _Note: cannot be used without an organization relationship_'
+          description: Relationships to the organization the domain will be scoped to and the organizations the domain will be shared with
         metadata:
           $ref: ../schemas/Metadata.yaml
+          description: Labels and annotations applied to the domain
     examples:
       default:
         summary: default
         value:
           name: example.com
           internal: false
+      identityAwareDomain:
+        summary: Identity-aware domain
+        value:
+          name: apps.identity
+          internal: false
+          enforce_route_policies: true
+          route_policies_scope: org

docs/openapi/apis/cf/latest/components/requestBodies/DomainUpdateRequestBody.yaml

@@ -7,4 +7,14 @@ content:
       properties:
         metadata:
           $ref: '../schemas/Metadata.yaml'
+          description: Labels and annotations applied to the domain
       description: Request schema for updating a domain
+    examples:
+      default:
+        summary: default
+        value:
+          metadata:
+            labels:
+              key: value
+            annotations:
+              note: detailed information

docs/openapi/apis/cf/latest/components/requestBodies/DropletCreateRequestBody.yaml

@@ -1,4 +1,5 @@
-description: Droplet object that needs to be created
+description: |-
+  Droplet object that needs to be created. When the `source_guid` query parameter is supplied the droplet is copied instead, and `relationships.app` (the destination app) is the only accepted parameter.
 required: true
 content:
   application/json:
@@ -15,9 +16,11 @@ content:
             - app
         process_types:
           type: object
-          description: Process names and start commands for the droplet
-        metadata:
-          $ref: ../schemas/Metadata.yaml
+          additionalProperties:
+            type: string
+          default:
+            web: ''
+          description: Process names and start commands for the droplet; not accepted when copying a droplet
       required:
         - relationships
       description: Request schema for creating a droplet
@@ -32,3 +35,10 @@ content:
           process_types:
             rake: bundle exec rake
             web: bundle exec rackup config.ru -p $PORT
+      copy:
+        summary: copy (with the source_guid query parameter)
+        value:
+          relationships:
+            app:
+              data:
+                guid: 7b34f1cf-7e73-428a-bb5a-8a17a8058396

docs/openapi/apis/cf/latest/components/requestBodies/DropletUpdateRequestBody.yaml

@@ -0,0 +1,23 @@
+description: Droplet object that needs to be updated
+required: true
+content:
+  application/json:
+    schema:
+      type: object
+      properties:
+        metadata:
+          $ref: ../schemas/Metadata.yaml
+          description: Labels and annotations applied to the droplet
+        image:
+          type: string
+          description: Image reference where the built complete image was stored (field can only be passed by Build State Updaters)
+      description: Request schema for updating a droplet
+    examples:
+      default:
+        summary: default
+        value:
+          metadata:
+            labels:
+              key: value
+            annotations:
+              note: detailed information

docs/openapi/apis/cf/latest/components/requestBodies/DropletUploadRequestBody.yaml

@@ -0,0 +1,17 @@
+description: A gzip compressed tarball file containing a Cloud Foundry compatible droplet, sent as part of a multi-part form
+required: true
+content:
+  multipart/form-data:
+    schema:
+      type: object
+      properties:
+        bits:
+          type: string
+          format: binary
+          description: A gzip compressed tarball file with `.tgz` extension containing the droplet bits
+      required:
+        - bits
+      description: Request schema for uploading droplet bits
+    encoding:
+      bits:
+        contentType: application/gzip

docs/openapi/apis/cf/latest/components/requestBodies/IsolationSegmentCreate.yaml

@@ -1,14 +1,16 @@
 description: Isolation segment to create
+required: true
 content:
   application/json:
     schema:
       type: object
       properties:
         name:
           type: string
-          description: Name of the isolation segment; isolation segment names must be unique across the entire system, and case is ignored when checking for uniqueness
+          description: Name of the isolation segment; must be unique (case-insensitive)
         metadata:
           $ref: ../schemas/Metadata.yaml
+          description: Labels and annotations applied to the isolation segment
       required:
         - name
     examples:

docs/openapi/apis/cf/latest/components/requestBodies/ManagedServiceInstanceUpdate.yaml

@@ -1,25 +1,32 @@
-description: Managed service instance to update
+description: Optional parameters for updating a managed service instance
+required: true
 content:
   application/json:
     schema:
-      type: object
-      properties:
-        name:
-          type: string
-          description: Name of the service instance
-        tags:
-          type: array
-          items:
-            type: string
-          description: Tags for the service instance
-        parameters:
-          type: object
-          description: Parameters for the service instance
-        relationships:
-          type: object
-          properties:
+      $ref: '../schemas/ManagedServiceInstanceUpdate.yaml'
+    examples:
+      managed_service_instance:
+        summary: Update managed service instance
+        value:
+          name: my_service_instance
+          parameters:
+            foo: bar
+            baz: qux
+          tags:
+            - foo
+            - bar
+            - baz
+          relationships:
             service_plan:
-              $ref: '../schemas/RelationshipToOne.yaml'
-          description: Relationships for the service instance
-        metadata:
-          $ref: '../schemas/Metadata.yaml'
+              data:
+                guid: f2b6ba9c-a4d2-11ea-8ae6-48bf6bec2d78
+          metadata:
+            annotations:
+              note: detailed information
+            labels:
+              key: value
+      managed_service_instance_upgrade:
+        summary: Upgrade managed service instance (maintenance_info update)
+        value:
+          maintenance_info:
+            version: 2.1.1