Add the Route Policies resource to the OpenAPI spec

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

@@ -0,0 +1,55 @@
+description: Route policy to create
+required: true
+content:
+  application/json:
+    schema:
+      type: object
+      properties:
+        source:
+          type: string
+          description: The policy selector. Must be `cf:app:<uuid>`, `cf:space:<uuid>`, `cf:org:<uuid>`, or `cf:any`
+        relationships:
+          type: object
+          properties:
+            route:
+              $ref: ../schemas/RelationshipToOne.yaml
+              description: The route this policy applies to
+          required:
+            - route
+          description: A relationship to the route this policy applies to
+        metadata:
+          $ref: ../schemas/Metadata.yaml
+          description: Labels and annotations applied to the route policy
+      required:
+        - source
+        - relationships
+    examples:
+      default:
+        summary: Allow specific app
+        value:
+          source: cf:app:d76446a1-f429-4444-8797-be2f78b75b08
+          relationships:
+            route:
+              data:
+                guid: 89b32bd6-688f-4424-b94f-2e2c86495a5f
+          metadata:
+            labels:
+              team: frontend
+            annotations:
+              description: Allow frontend app to call backend API
+      space:
+        summary: Allow all apps in a space
+        value:
+          source: cf:space:3fa85f64-5717-4562-b3fc-2c963f66afa6
+          relationships:
+            route:
+              data:
+                guid: 89b32bd6-688f-4424-b94f-2e2c86495a5f
+      any:
+        summary: Allow any caller
+        value:
+          source: cf:any
+          relationships:
+            route:
+              data:
+                guid: 89b32bd6-688f-4424-b94f-2e2c86495a5f

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

@@ -0,0 +1,19 @@
+description: Route policy metadata to update
+required: true
+content:
+  application/json:
+    schema:
+      type: object
+      properties:
+        metadata:
+          $ref: ../schemas/Metadata.yaml
+          description: Labels and annotations applied to the route policy
+    examples:
+      default:
+        summary: default
+        value:
+          metadata:
+            labels:
+              team: backend
+            annotations:
+              note: Updated contact info

docs/openapi/apis/cf/latest/components/schemas/RoutePolicy.yaml

@@ -0,0 +1,65 @@
+type: object
+allOf:
+  - $ref: './BaseSchema.yaml'
+  - properties:
+      source:
+        type: string
+        description: |-
+          The policy selector specifying who can access the route. Must be one of:
+          - `cf:app:<uuid>` (specific app)
+          - `cf:space:<uuid>` (all apps in a space)
+          - `cf:org:<uuid>` (all apps in an organization)
+          - `cf:any` (any caller - cannot be combined with other sources)
+      metadata:
+        $ref: './Metadata.yaml'
+        description: Labels and annotations applied to the route policy
+      relationships:
+        type: object
+        properties:
+          route:
+            $ref: './RelationshipToOne.yaml'
+            description: The route this policy applies to
+          app:
+            $ref: './RelationshipToOne.yaml'
+            description: Read-only. Always present; `data` is `null` unless the source is `cf:app:<uuid>`
+          space:
+            $ref: './RelationshipToOne.yaml'
+            description: Read-only. Always present; `data` is `null` unless the source is `cf:space:<uuid>`
+          organization:
+            $ref: './RelationshipToOne.yaml'
+            description: Read-only. Always present; `data` is `null` unless the source is `cf:org:<uuid>`
+        description: Relationships to the route this policy applies to and to the app, space, or organization referenced by the source
+      links:
+        type: object
+        properties:
+          self:
+            $ref: './Link.yaml'
+            description: The URL to get this route policy
+          route:
+            $ref: './Link.yaml'
+            description: The URL to get the route this policy applies to
+          app:
+            $ref: './Link.yaml'
+            description: The URL to get the app referenced by the source; only present when the source is `cf:app:<uuid>`
+          space:
+            $ref: './Link.yaml'
+            description: The URL to get the space referenced by the source; only present when the source is `cf:space:<uuid>`
+          organization:
+            $ref: './Link.yaml'
+            description: The URL to get the organization referenced by the source; only present when the source is `cf:org:<uuid>`
+        description: Links to related resources. Always includes `self` and `route`; includes `app`, `space`, or `organization` when the source references that resource
+      included:
+        $ref: './IncludedResources.yaml'
+        description: Additional related resources included in the response when using the include parameter
+description: |-
+  Route policies control which Cloud Foundry apps, spaces, or organizations can access routes on identity-aware domains. When a domain has `enforce_route_policies` enabled, GoRouter automatically enforces these access controls using mutual TLS (mTLS) to verify the identity of the calling application.
+
+  Route policies are defined using a `source` selector that specifies who can access the route:
+  - `cf:app:<uuid>` - Allow a specific app
+  - `cf:space:<uuid>` - Allow all apps in a space
+  - `cf:org:<uuid>` - Allow all apps in an organization
+  - `cf:any` - Allow any caller (cannot be combined with other sources on the same route)
+
+  > **Note:** Route policies can only be created for routes on domains where `enforce_route_policies` is `true` and the domain is not internal (internal routes use container-to-container networking and bypass GoRouter).
+
+  **This feature is experimental and is subject to change.**

docs/openapi/apis/cf/latest/components/schemas/RoutePolicyList.yaml

@@ -0,0 +1,13 @@
+type: object
+properties:
+  pagination:
+    $ref: './Pagination.yaml'
+  resources:
+    type: array
+    items:
+      $ref: './RoutePolicy.yaml'
+    description: List of route policies
+  included:
+    $ref: './IncludedResources.yaml'
+    description: Additional related resources included in the response when using the include parameter
+description: A list of route policies

docs/openapi/apis/cf/latest/openapi.yaml

@@ -60,6 +60,8 @@ tags:
     description: "Root API endpoints that provide entry points and API information."
   - name: Routes
     description: "Routes are used to map a URL to an app."
+  - name: Route Policies
+    description: "Route policies control which callers can access routes on identity-aware domains."
   - name: Security Groups
     description: "Security groups are used to control access to apps."
   - name: Service Brokers
@@ -464,6 +466,10 @@ paths:
     $ref: './paths/Roles.yaml#/~1v3~1roles'
   /v3/roles/{guid}:
     $ref: './paths/Roles.yaml#/~1v3~1roles~1{guid}'
+  /v3/route_policies:
+    $ref: './paths/RoutePolicies.yaml#/~1v3~1route_policies'
+  /v3/route_policies/{guid}:
+    $ref: './paths/RoutePolicies.yaml#/~1v3~1route_policies~1{guid}'
   /v3/routes:
     $ref: './paths/Routes.yaml#/~1v3~1routes'
   /v3/routes/{guid}/destinations: