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/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/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

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

@@ -4,18 +4,19 @@ content:
   application/json:
     schema:
       type: object
+      description: Request schema for creating an organization
       properties:
         name:
           type: string
-          description: Organization name
+          description: Organization name; must be unique (case-insensitive)
         suspended:
           type: boolean
           description: Whether an organization is suspended or not
         metadata:
           $ref: ../schemas/Metadata.yaml
+          description: Labels and annotations applied to the organization
       required:
         - name
-      description: Request schema for creating an organization
     examples:
       default:
         summary: default