From b7600cf5a8010cde5225110dcd9aa9a2f7e49096 Mon Sep 17 00:00:00 2001
From: Si Beaumont <beaumont@apple.com>
Date: Thu, 5 Oct 2023 19:06:48 +0100
Subject: [PATCH] v2: Operation-level filtering by tag and ID

Signed-off-by: Si Beaumont <beaumont@apple.com>
---
 .../Documentation.docc/Proposals/SOAR-0008.md | 89 ++++++++++++-------
 1 file changed, 59 insertions(+), 30 deletions(-)

diff --git a/Sources/swift-openapi-generator/Documentation.docc/Proposals/SOAR-0008.md b/Sources/swift-openapi-generator/Documentation.docc/Proposals/SOAR-0008.md
index 5ca579e1..46474408 100644
--- a/Sources/swift-openapi-generator/Documentation.docc/Proposals/SOAR-0008.md
+++ b/Sources/swift-openapi-generator/Documentation.docc/Proposals/SOAR-0008.md
@@ -20,6 +20,9 @@ Filtering the OpenAPI document for just the required parts prior to generating.
     - [Project scope and goals](https://swiftpackageindex.com/apple/swift-openapi-generator/documentation/swift-openapi-generator/project-scope-and-goals)
 - Versions:
     - v1 (2023-09-28): Initial version
+    - v2 (2023-10-05):
+      - Filtering by tag only includes the tagged operations (cf. whole path)
+      - Add support for filtering operations by ID
 
 ### Introduction
 
@@ -156,6 +159,8 @@ generator.
 #   - ...
 #   tags:
 #   - ...
+#   operations:
+#   - ...
 #   schemas:
 #   - ...
 ```
@@ -175,8 +180,6 @@ filter:
   - issues
 ```
 
-
-
 When this config key is present, the OpenAPI document will be filtered, before
 generation, to contain the paths and schemas requested, along with the
 transitive closure of components on which they depend.
@@ -188,8 +191,8 @@ The following filters will be supported:
 
 - `paths`: Includes the given paths, specified using the same keys as '#/paths'
   in the OpenAPI document.
-- `tags`: Includes any path that contain any operation with any of the given
-  tags.
+- `tags`: Includes the operations with any of the given tags.
+- `operations`: Includes the operations with these explicit operation IDs.
 - `schemas`: Includes any schemas, specifid using the same keys as
   '#/components/schemas' in the OpenAPI document.
 
@@ -225,9 +228,12 @@ a new, optional property has been added:
 /// Rules used to filter an OpenAPI document.
 struct DocumentFilter: Codable, Sendable {
 
-    /// Paths that contain operations with these tags will be included.
+    /// Operations with these tags will be included.
     var tags: [String]?
 
+    /// Operations with these IDs will be included.
+    var operations: [String]?
+
     /// These paths will be included in the filter.
     var paths: [OpenAPI.Path]?
 
@@ -250,28 +256,6 @@ This change is purely API additive:
 
 ### Future directions
 
-#### More precise filtering
-
-Although tags are applied to operations in the OpenAPI specification, the unit
-of inclusion of the filter is a path item.
-
-Consequently, if only one operation within a path is tagged, the output of the
-filter will contain the entire path item. That is, you get _at least_ what you
-asked for.
-
-This greatly simplifies the implemnentation of the filter and is the most
-natural unit for manipulating the document. Specifically path items are now
-part of the component object (cf. operations).
-
-Future implementations may make this more precise, and may further filter the
-path items to only include the tagged operations.
-
-#### Including operations by operation ID
-
-Relatedly, if it becomes possible to include specific operations (cf. whole
-path items), then it would make sense to be able to include operations by the
-operation ID, if it is provided in the OpenAPI document.
-
 #### Providing a `fitler` CLI command
 
 Filtering the OpenAPI document has general utility beyond use within the
@@ -313,13 +297,20 @@ tags:
 paths:
   /things/a:
     get:
+      operationId: getA
       tags:
       - t
       responses:
         200:
           $ref: '#/components/responses/A'
+    delete:
+      operationId: deleteA
+      responses:
+        200:
+          $ref: '#/components/responses/Empty'
   /things/b:
     get:
+      operationId: getB
       responses:
         200:
           $ref: '#/components/responses/B'
@@ -342,6 +333,8 @@ components:
         application/json:
           schema:
             $ref: '#/components/schemas/B'
+    Empty:
+      description: success
 ```
 
 #### Including paths by key
@@ -367,6 +360,7 @@ tags:
 paths:
   /things/b:
     get:
+      operationId: getB
       responses:
         200:
           $ref: '#/components/responses/B'
@@ -386,7 +380,7 @@ components:
 ```
 </details>
 
-#### Including paths that contain an operation with a tag
+#### Including operations by tag
 
 ```yaml
 # openapi-generator-config.yaml
@@ -411,6 +405,7 @@ paths:
     get:
       tags:
       - t
+      operationId: getA
       responses:
         200:
           $ref: '#/components/responses/A'
@@ -450,10 +445,44 @@ tags:
 - name: t
 components:
   schemas:
-    B:
-      $ref: '#/components/schemas/A'
     A:
       type: string
+    B:
+      $ref: '#/components/schemas/A'
+```
+</details>
+
+#### Including operations by ID
+
+```yaml
+# openapi-generator-config.yaml
+filter:
+  operations:
+  - deleteA
+```
+
+<details>
+<summary>Click to expand filtered document</summary>
+
+```yaml
+# filtered OpenAPI document
+openapi: 3.1.0
+info:
+  title: ExampleService
+  version: 1.0.0
+tags:
+- name: t
+paths:
+  /things/a:
+    delete:
+      operationId: deleteA
+      responses:
+        200:
+          $ref: '#/components/responses/Empty'
+components:
+  responses:
+    Empty:
+      description: success
 ```
 </details>