Rest API tweaks for docs (#6182)

* Remove "Public Only Endpoints" tag. OpenAPI-Generator doesn't give nice output with multiple tags. (e.g. it generates multiple copies of the same link in the generated navigation) As discussed with Ben & Isaac, the multiple tags aren't hugely important so we've already removed in most places, but looks like I missed Public Only Endpoints in my previous commit. * Add operationId to all operations. This is recommended by OpenAPI Spec, and makes openapi-generator and some of the Docs tooling happy. I've generated these based on the METHOD + FILENAME and updated in batch with a bash + yq script. * Update .redocly.yaml As advised by @bbrks as this will verify that all endpoints have an operationID.
couchbase · Apr 12, 2023 · 469b1e7 · 469b1e7
1 parent 90377a6
commit 469b1e7
Show file tree

Hide file tree

Showing 106 changed files with 195 additions and 110 deletions.
diff --git a/.redocly.yaml b/.redocly.yaml
@@ -22,7 +22,6 @@ lint:
   rules:
     # disable unnecessary/invalid warnings
     operation-2xx-response: off # _blipsync 101 Upgrade ...
-    operation-operationId: off  # Optional (mostly used for generating code)
     operation-summary: off      # Optional field
     no-ambiguous-paths: off     # /{db}/{doc} != /_debug/expvar
     no-identical-paths: off     # /{db} != /{targetdb}

diff --git a/docs/api/paths/admin/-.yaml b/docs/api/paths/admin/-.yaml
@@ -5,7 +5,6 @@
 # in that file, in accordance with the Business Source License, use of this
 # software will be governed by the Apache License, Version 2.0, included in
 # the file licenses/APL2.txt.
-
 get:
   summary: Get server information
   description: Returns information about the Sync Gateway node.
@@ -18,6 +17,7 @@ get:
             $ref: ../../components/schemas.yaml#/NodeInfo
   tags:
     - Server
+  operationId: get_-
 head:
   responses:
     '200':
@@ -26,3 +26,4 @@ head:
     - Server
   summary: Check if server online
   description: Check if the server is online by checking the status code of response.
+  operationId: head_-
diff --git a/docs/api/paths/admin/_all_dbs.yaml b/docs/api/paths/admin/_all_dbs.yaml
@@ -5,7 +5,6 @@
 # in that file, in accordance with the Business Source License, use of this
 # software will be governed by the Apache License, Version 2.0, included in
 # the file licenses/APL2.txt.
-
 get:
   summary: Get a list of all the databases
   description: |-
@@ -25,6 +24,7 @@ get:
               type: string
   tags:
     - Database Management
+  operationId: get__all_dbs
 head:
   summary: /_all_dbs
   description: |-
@@ -36,3 +36,4 @@ head:
       description: OK
   tags:
     - Database Management
+  operationId: head__all_dbs
diff --git a/docs/api/paths/admin/_config.yaml b/docs/api/paths/admin/_config.yaml
@@ -5,7 +5,6 @@
 # in that file, in accordance with the Business Source License, use of this
 # software will be governed by the Apache License, Version 2.0, included in
 # the file licenses/APL2.txt.
-
 get:
   summary: Get server configuration
   description: |-
@@ -33,6 +32,7 @@ get:
       $ref: ../../components/responses.yaml#/request-problem
   tags:
     - Server
+  operationId: get__config
 put:
   summary: Set runtime configuration
   description: |-
@@ -57,3 +57,4 @@ put:
       $ref: ../../components/responses.yaml#/request-problem
   tags:
     - Server
+  operationId: put__config
diff --git a/docs/api/paths/admin/_debug-fgprof.yaml b/docs/api/paths/admin/_debug-fgprof.yaml
@@ -5,7 +5,6 @@
 # in that file, in accordance with the Business Source License, use of this
 # software will be governed by the Apache License, Version 2.0, included in
 # the file licenses/APL2.txt.
-
 get:
   summary: Get fgprof profile
   description: |-
@@ -25,6 +24,7 @@ get:
             type: string
   tags:
     - Profiling
+  operationId: get__debug-fgprof
 post:
   summary: Get fgprof profile
   description: |-
@@ -44,3 +44,4 @@ post:
             type: string
   tags:
     - Profiling
+  operationId: post__debug-fgprof
diff --git a/docs/api/paths/admin/_debug-pprof-block.yaml b/docs/api/paths/admin/_debug-pprof-block.yaml
@@ -5,7 +5,6 @@
 # in that file, in accordance with the Business Source License, use of this
 # software will be governed by the Apache License, Version 2.0, included in
 # the file licenses/APL2.txt.
-
 get:
   summary: Get block profile
   description: |-
@@ -30,6 +29,7 @@ get:
             reason: Can only run one mutex profile at a time
   tags:
     - Profiling
+  operationId: get__debug-pprof-block
 post:
   summary: Get block profile
   description: |-
@@ -54,3 +54,4 @@ post:
             reason: Can only run one mutex profile at a time
   tags:
     - Profiling
+  operationId: post__debug-pprof-block
diff --git a/docs/api/paths/admin/_debug-pprof-cmdline.yaml b/docs/api/paths/admin/_debug-pprof-cmdline.yaml
@@ -5,7 +5,6 @@
 # in that file, in accordance with the Business Source License, use of this
 # software will be governed by the Apache License, Version 2.0, included in
 # the file licenses/APL2.txt.
-
 get:
   summary: Get passed in command line parameters
   description: |-
@@ -23,6 +22,7 @@ get:
             type: string
   tags:
     - Profiling
+  operationId: get__debug-pprof-cmdline
 post:
   summary: Get passed in command line parameters
   description: |-
@@ -40,3 +40,4 @@ post:
             type: string
   tags:
     - Profiling
+  operationId: post__debug-pprof-cmdline
diff --git a/docs/api/paths/admin/_debug-pprof-goroutine.yaml b/docs/api/paths/admin/_debug-pprof-goroutine.yaml
@@ -5,7 +5,6 @@
 # in that file, in accordance with the Business Source License, use of this
 # software will be governed by the Apache License, Version 2.0, included in
 # the file licenses/APL2.txt.
-
 get:
   summary: Get goroutine profile
   description: |-
@@ -21,6 +20,7 @@ get:
       $ref: ../../components/responses.yaml#/pprof-binary
   tags:
     - Profiling
+  operationId: get__debug-pprof-goroutine
 post:
   summary: Get goroutine profile
   description: |-
@@ -36,3 +36,4 @@ post:
       $ref: ../../components/responses.yaml#/pprof-binary
   tags:
     - Profiling
+  operationId: post__debug-pprof-goroutine
diff --git a/docs/api/paths/admin/_debug-pprof-heap.yaml b/docs/api/paths/admin/_debug-pprof-heap.yaml
@@ -5,7 +5,6 @@
 # in that file, in accordance with the Business Source License, use of this
 # software will be governed by the Apache License, Version 2.0, included in
 # the file licenses/APL2.txt.
-
 get:
   summary: Get the heap pprof debug file
   description: |-
@@ -19,6 +18,7 @@ get:
       $ref: ../../components/responses.yaml#/pprof-binary
   tags:
     - Profiling
+  operationId: get__debug-pprof-heap
 post:
   summary: Get the heap pprof debug file
   description: |-
@@ -32,3 +32,4 @@ post:
       $ref: ../../components/responses.yaml#/pprof-binary
   tags:
     - Profiling
+  operationId: post__debug-pprof-heap
diff --git a/docs/api/paths/admin/_debug-pprof-mutex.yaml b/docs/api/paths/admin/_debug-pprof-mutex.yaml
@@ -5,7 +5,6 @@
 # in that file, in accordance with the Business Source License, use of this
 # software will be governed by the Apache License, Version 2.0, included in
 # the file licenses/APL2.txt.
-
 get:
   summary: Get mutex profile
   description: |-
@@ -30,6 +29,7 @@ get:
             reason: Can only run one mutex profile at a time
   tags:
     - Profiling
+  operationId: get__debug-pprof-mutex
 post:
   summary: Get mutex profile
   description: |-
@@ -54,3 +54,4 @@ post:
             reason: Can only run one mutex profile at a time
   tags:
     - Profiling
+  operationId: post__debug-pprof-mutex
diff --git a/docs/api/paths/admin/_debug-pprof-profile.yaml b/docs/api/paths/admin/_debug-pprof-profile.yaml
@@ -5,7 +5,6 @@
 # in that file, in accordance with the Business Source License, use of this
 # software will be governed by the Apache License, Version 2.0, included in
 # the file licenses/APL2.txt.
-
 get:
   summary: Get the profile pprof debug file
   description: |-
@@ -19,6 +18,7 @@ get:
       $ref: ../../components/responses.yaml#/pprof-binary
   tags:
     - Profiling
+  operationId: get__debug-pprof-profile
 post:
   summary: Get the profile pprof debug file
   description: |-
@@ -32,3 +32,4 @@ post:
       $ref: ../../components/responses.yaml#/pprof-binary
   tags:
     - Profiling
+  operationId: post__debug-pprof-profile
diff --git a/docs/api/paths/admin/_debug-pprof-symbol.yaml b/docs/api/paths/admin/_debug-pprof-symbol.yaml
@@ -5,7 +5,6 @@
 # in that file, in accordance with the Business Source License, use of this
 # software will be governed by the Apache License, Version 2.0, included in
 # the file licenses/APL2.txt.
-
 get:
   summary: Get symbol pprof debug information
   description: |-
@@ -21,6 +20,7 @@ get:
             type: string
   tags:
     - Profiling
+  operationId: get__debug-pprof-symbol
 post:
   summary: Get symbol pprof debug information
   description: |-
@@ -36,3 +36,4 @@ post:
             type: string
   tags:
     - Profiling
+  operationId: post__debug-pprof-symbol
diff --git a/docs/api/paths/admin/_debug-pprof-threadcreate.yaml b/docs/api/paths/admin/_debug-pprof-threadcreate.yaml
@@ -5,7 +5,6 @@
 # in that file, in accordance with the Business Source License, use of this
 # software will be governed by the Apache License, Version 2.0, included in
 # the file licenses/APL2.txt.
-
 get:
   summary: Get the threadcreate pprof debug file
   description: |-
@@ -17,6 +16,7 @@ get:
       $ref: ../../components/responses.yaml#/pprof-binary
   tags:
     - Profiling
+  operationId: get__debug-pprof-threadcreate
 post:
   summary: Get the threadcreate pprof debug file
   description: |-
@@ -28,3 +28,4 @@ post:
       $ref: ../../components/responses.yaml#/pprof-binary
   tags:
     - Profiling
+  operationId: post__debug-pprof-threadcreate
diff --git a/docs/api/paths/admin/_debug-pprof-trace.yaml b/docs/api/paths/admin/_debug-pprof-trace.yaml
@@ -5,7 +5,6 @@
 # in that file, in accordance with the Business Source License, use of this
 # software will be governed by the Apache License, Version 2.0, included in
 # the file licenses/APL2.txt.
-
 get:
   summary: Get trace profile
   description: |-
@@ -25,6 +24,7 @@ get:
       $ref: ../../components/responses.yaml#/pprof-binary
   tags:
     - Profiling
+  operationId: get__debug-pprof-trace
 post:
   summary: Get trace profile
   description: |-
@@ -44,3 +44,4 @@ post:
       $ref: ../../components/responses.yaml#/pprof-binary
   tags:
     - Profiling
+  operationId: post__debug-pprof-trace
diff --git a/docs/api/paths/admin/_expvar.yaml b/docs/api/paths/admin/_expvar.yaml
@@ -5,7 +5,6 @@
 # in that file, in accordance with the Business Source License, use of this
 # software will be governed by the Apache License, Version 2.0, included in
 # the file licenses/APL2.txt.
-
 get:
   summary: Get all Sync Gateway statistics
   description: |-
@@ -27,3 +26,4 @@ get:
             $ref: ../../components/schemas.yaml#/ExpVars
   tags:
     - Metrics
+  operationId: get__expvar
diff --git a/docs/api/paths/admin/_heap.yaml b/docs/api/paths/admin/_heap.yaml
@@ -5,7 +5,6 @@
 # in that file, in accordance with the Business Source License, use of this
 # software will be governed by the Apache License, Version 2.0, included in
 # the file licenses/APL2.txt.
-
 post:
   summary: Dump heap profile
   description: |-
@@ -23,3 +22,4 @@ post:
       $ref: ../../components/responses.yaml#/request-problem
   tags:
     - Profiling
+  operationId: post__heap
diff --git a/docs/api/paths/admin/_logging.yaml b/docs/api/paths/admin/_logging.yaml
@@ -5,7 +5,6 @@
 # in that file, in accordance with the Business Source License, use of this
 # software will be governed by the Apache License, Version 2.0, included in
 # the file licenses/APL2.txt.
-
 get:
   summary: Get console logging settings
   description: |-
@@ -25,6 +24,7 @@ get:
   deprecated: true
   tags:
     - Server
+  operationId: get__logging
 put:
   summary: Set console logging settings
   description: |-
@@ -51,6 +51,7 @@ put:
   deprecated: true
   tags:
     - Server
+  operationId: put__logging
 post:
   summary: Update console logging settings
   description: |-
@@ -77,3 +78,4 @@ post:
   deprecated: true
   tags:
     - Server
+  operationId: post__logging
diff --git a/docs/api/paths/admin/_post_upgrade.yaml b/docs/api/paths/admin/_post_upgrade.yaml
@@ -5,7 +5,6 @@
 # in that file, in accordance with the Business Source License, use of this
 # software will be governed by the Apache License, Version 2.0, included in
 # the file licenses/APL2.txt.
-
 post:
   summary: Run the post upgrade process on all databases
   description: |-
@@ -56,3 +55,4 @@ post:
               - post_upgrade_results
   tags:
     - Server
+  operationId: post__post_upgrade
diff --git a/docs/api/paths/admin/_profile-profilename.yaml b/docs/api/paths/admin/_profile-profilename.yaml
@@ -5,7 +5,6 @@
 # in that file, in accordance with the Business Source License, use of this
 # software will be governed by the Apache License, Version 2.0, included in
 # the file licenses/APL2.txt.
-
 parameters:
   - name: profilename
     in: path
@@ -38,3 +37,4 @@ post:
       $ref: ../../components/responses.yaml#/Not-found
   tags:
     - Profiling
+  operationId: post__profile-profilename
diff --git a/docs/api/paths/admin/_profile.yaml b/docs/api/paths/admin/_profile.yaml
@@ -5,7 +5,6 @@
 # in that file, in accordance with the Business Source License, use of this
 # software will be governed by the Apache License, Version 2.0, included in
 # the file licenses/APL2.txt.
-
 post:
   summary: Start or Stop continuous CPU profiling
   description: |-
@@ -27,3 +26,4 @@ post:
       $ref: ../../components/responses.yaml#/request-problem
   tags:
     - Profiling
+  operationId: post__profile