chore: Update Open API specification (#686)

2025-10-27 11:02:16 +01:00 · 2021-01-25 06:57:40 +00:00 · 2021-01-25 06:57:40 +00:00 · 9e31800bf4
commit 9e31800bf4
parent 7c5b914513
1 changed files with 261 additions and 229 deletions
--- a/docs/api/oas/openapi.yaml
+++ b/docs/api/oas/openapi.yaml
@ -90,11 +90,13 @@ paths:
        '400':
          description: 'Bad body request (for example, appName is not correct)'
        '401':
-          description: Not authorized
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/401' 
+          $ref: '#/components/responses/notAuthorizedResponse'
+      x-code-samples:
+        - lang: 'cURL'
+          source: |
+            curl --request POST \
+              --url http://localhost:4242/api/client/register \
+              --data '{"appName":"my-application","instanceId":"generated-732038-17080","sdkVersion":"unleash-client-node:3.4.0","strategies":[{"strategy":"default"}],"started":"2016-11-03T07:16:43.572Z","interval":10000}'
  /client/metrics:
    post:
      summary: Register a metrics *bucket*.
@ -115,11 +117,13 @@ paths:
        '400':
          description: 'Bad body request (for example, appName is not correct)'
        '401':
-          description: Not authorized
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/401'
+          $ref: '#/components/responses/notAuthorizedResponse'
+      x-code-samples:
+        - lang: 'cURL'
+          source: |
+            curl --request POST \
+              --url http://localhost:4242/api/client/metrics \
+              --data '{"appName":"my-application","instanceId":"generated-732038-17080","bucket":{"start":"2020-12-08T13:50:00.000Z","stop":"2020-12-08T13:55:00.000Z","toggles":{"yesno":{"yesorno":"yes"},"metricsCount":{"count":1}}}}'
  /client/features:
    # Would normally $ref here but it tangles with an OAS bug - which affects both Redoc and Swagger UI - https://github.com/swagger-api/swagger-ui/issues/6249 (closed issue but still broken in latest release)
    get:
@ -137,17 +141,14 @@ paths:
        - Feature toggles
      responses:
        '200':
-          description: Successful response
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/200client'
+          $ref: '#/components/responses/clientResponse'
        '401':
-          description: Not authorized
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/401'
+          $ref: '#/components/responses/notAuthorizedResponse'
+      x-code-samples:
+        - lang: 'cURL'
+          source: |
+            curl --request GET \
+              --url http://localhost:4242/api/client/features
  '/client/features/{featureName}':
    get:
      summary: Fetches a specific Feature Toggle from the Unleash server.
@ -167,17 +168,14 @@ paths:
        - Feature toggles
      responses:
        '200':
-          description: Successful response
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/200'
+          $ref: '#/components/responses/successResponse'
        '401':
-          description: Not authorized
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/401'
+          $ref: '#/components/responses/notAuthorizedResponse'
+      x-code-samples:
+        - lang: 'cURL'
+          source: |
+            curl --request GET \
+              --url http://localhost:4242/api/client/features/featureName
  /admin/features:
    get:
      summary: Fetches all feature toggles from the Unleash server.
@ -193,17 +191,14 @@ paths:
        - Feature toggles
      responses:
        '200':
-          description: Successful response
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/200'
+          $ref: '#/components/responses/successResponse'
        '401':
-          description: Not authorized
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/401'
+          $ref: '#/components/responses/notAuthorizedResponse'
+      x-code-samples:
+        - lang: 'cURL'
+          source: |
+            curl --request GET \
+              --url http://localhost:4242/api/admin/features
    post:
      summary: Create a Feature Toggle
      description: Create a new Feature Toggle
@ -222,11 +217,13 @@ paths:
        '400':
          description: 'Bad body request (for example, Feature Toggle name is not unique)'
        '401':
-          description: Not authorized
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/401'
+          $ref: '#/components/responses/notAuthorizedResponse'
+      x-code-samples:
+        - lang: 'cURL'
+          source: |
+            curl --request POST \
+              --url http://localhost:4242/api/admin/features \
+              --data '[{"name":"featureX","description":"Toggles featureX on and off","type":"release","enabled":true,"stale":false,"strategies":[{"name":"default","editable":true,"description":"Default on/off strategy.","parameters":{"parameter":{"name":"groupId","type":"string","description":"Define activation groups to allow you to correlate across feature toggles.","required":false}}}],"variants":[{"name":"yellow","weight":20}],"createdAt":"string"}]'
  '/admin/features/{featureName}':
    get:
      summary: Fetches a specific Feature Toggle from the Unleash server.
@ -244,17 +241,14 @@ paths:
        - Feature toggles
      responses:
        '200':
-          description: Successful response
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/200'
+          $ref: '#/components/responses/successResponse'
        '401':
-          description: Not authorized
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/401'
+          $ref: '#/components/responses/notAuthorizedResponse'
+      x-code-samples:
+        - lang: 'cURL'
+          source: |
+            curl --request GET \
+              --url http://localhost:4242/api/admin/features/featureName
    put:
      summary: Update a Feature Toggle
      description: Update a Feature Toggle.
@ -271,22 +265,19 @@ paths:
              $ref: '#/components/schemas/featureToggleSchema'
      responses:
        '200':
-          description: Feature Toggle successfully updated
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/200'
+          $ref: '#/components/responses/successResponse'
+        '401':
+          $ref: '#/components/responses/notAuthorizedResponse'
        '400':
          description: Bad body request (for example 'strategies' is not an array)
-        '401':
-          description: Not authorized
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/401'
        '404':
          description: Feature Toggle not found
      x-code-samples:
+        - lang: 'cURL'
+          source: |
+            curl --request PUT \
+              --url http://localhost:4242/api/admin/features/featureName \
+              --data '[{"name":"featureX","description":"Toggles featureX on and off","type":"release","enabled":true,"stale":false,"strategies":[{"name":"default","editable":true,"description":"Default on/off strategy.","parameters":{"parameter":{"name":"groupId","type":"string","description":"Define activation groups to allow you to correlate across feature toggles.","required":false}}}],"variants":[{"name":"yellow","weight":20}],"createdAt":"string"}]'
        - lang: 'Go'
          source: |
            package main
@ -362,13 +353,14 @@ paths:
        '200':
          description: Feature Toggle successfully archived
        '401':
-          description: Not authorized
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/401'
+          $ref: '#/components/responses/notAuthorizedResponse'
        '404':
          description: Feature Toggle not found
+      x-code-samples:
+        - lang: 'cURL'
+          source: |
+            curl --request DELETE \
+              --url http://localhost:4242/api/admin/features/featureName
  '/admin/features/{featureName}/toggle/on':
    post:
      summary: Enable a Feature Toggle.
@ -380,19 +372,16 @@ paths:
        - $ref: '#/components/parameters/featureNamePath'
      responses:
        '200':
-          description: Successful response
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/200'
+          $ref: '#/components/responses/successResponse'
        '401':
-          description: Not authorized
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/401'
+          $ref: '#/components/responses/notAuthorizedResponse'
        '404':
          description: Feature Toggle not found
+      x-code-samples:
+        - lang: 'cURL'
+          source: |
+            curl --request POST \
+              --url http://localhost:4242/api/admin/features/featureName/toggle/on
  '/admin/features/{featureName}/toggle/off':
    post:
      summary: Disable a Feature Toggle.
@ -404,19 +393,16 @@ paths:
        - $ref: '#/components/parameters/featureNamePath'
      responses:
        '200':
-          description: Successful response
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/200'
+          $ref: '#/components/responses/successResponse'
        '401':
-          description: Not authorized
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/401'
+          $ref: '#/components/responses/notAuthorizedResponse'
        '404':
          description: Feature Toggle not found
+      x-code-samples:
+        - lang: 'cURL'
+          source: |
+            curl --request POST \
+            --url http://localhost:4242/api/admin/features/featureName/toggle/off
  '/admin/features/{featureName}/stale/on':
    post:
      summary: Mark a Feature Toggle as 'stale' (deprecated).
@ -431,19 +417,16 @@ paths:
        - $ref: '#/components/parameters/featureNamePath'
      responses:
        '200':
-          description: Successful response
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/200'
+          $ref: '#/components/responses/successResponse'
        '401':
-          description: Not authorized
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/401'
+          $ref: '#/components/responses/notAuthorizedResponse'
        '404':
          description: Feature Toggle not found
+      x-code-samples:
+        - lang: 'cURL'
+          source: |
+            curl --request POST \
+            --url http://localhost:4242/api/admin/features/featureName/stale/on
  '/admin/features/{featureName}/stale/off':
    post:
      summary: Mark a Feature Toggle as active.
@ -458,19 +441,16 @@ paths:
        - $ref: '#/components/parameters/featureNamePath'
      responses:
        '200':
-          description: Successful response
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/200'
+          $ref: '#/components/responses/successResponse'
        '401':
-          description: Not authorized
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/401'
+          $ref: '#/components/responses/notAuthorizedResponse'
        '404':
          description: Feature Toggle not found
+      x-code-samples:
+        - lang: 'cURL'
+          source: |
+            curl --request POST \
+              --url http://localhost:4242/api/admin/features/featureName/stale/off
  /admin/archive/features:
    get:
      summary: List all the archived feature toggles on the Unleash server
@ -480,19 +460,16 @@ paths:
        - Archive
      responses:
        '200':
-          description: Successful response
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/200'
+          $ref: '#/components/responses/successResponse'
        '401':
-          description: Not authorized
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/401'
+          $ref: '#/components/responses/notAuthorizedResponse'
        '404':
          description: Feature Toggle not found
+      x-code-samples:
+        - lang: 'cURL'
+          source: |
+            curl --request GET \
+             --url http://localhost:4242/api/admin/archive/features
  '/admin/archive/revive/{featureName}':
    post:
      summary: Un-archive a Feature Toggle
@ -507,6 +484,11 @@ paths:
          description: Feature Toggle successfully revived
        '404':
          description: Feature Toggle not found
+      x-code-samples:
+        - lang: 'cURL'
+          source: |
+            curl --request POST \
+              --url http://localhost:4242/api/admin/archive/revive/featureName
  /admin/strategies:
    get:
      summary: Fetch all strategies and their parameters.
@ -516,17 +498,14 @@ paths:
        - Strategies
      responses:
        '200':
-          description: Successful response
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/200strategy'
+          $ref: '#/components/responses/strategyExistsResponse'
        '401':
-          description: Not authorized
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/401'
+          $ref: '#/components/responses/notAuthorizedResponse'
+      x-code-samples:
+        - lang: 'cURL'
+          source: |
+            curl --request GET \
+              --url http://localhost:4242/api/admin/strategies
    post:
      summary: Create Strategy
      description: Create Strategy
@ -545,17 +524,15 @@ paths:
        '400':
          description: Bad body request (for example 'strategies' is not an array)
        '401':
-          description: Not authorized
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/401'
+          $ref: '#/components/responses/notAuthorizedResponse'
        '409':
-          description: Strategy already exists
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/409'
+          $ref: '#/components/responses/strategyExistsResponse'
+      x-code-samples:
+        - lang: 'cURL'
+          source: |
+            curl --request POST \
+              --url http://localhost:4242/api/admin/strategies \
+              --data '{"name":"gradualRollout","description":"Gradual rollout to logged in users","parameters":[{"name":"percentage","type":"percentage","description":"What percent of users should the new Feature Toggle be active for?","required":true}]}'
  '/admin/strategies/{strategyName}':
    put:
      summary: Update Strategy
@ -580,13 +557,15 @@ paths:
        '200':
          description: Strategy successfully updated.
        '401':
-          description: Not authorized
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/401'
+          $ref: '#/components/responses/notAuthorizedResponse'
        '404':
          description: Strategy not updated due to errors in query and/or request body (such as **name** and **strategyName** not matching).
+      x-code-samples:
+        - lang: 'cURL'
+          source: |
+            curl --request PUT \
+              --url http://localhost:4242/api/admin/strategies/strategyName \
+              --data '{"name":"gradualRollout","description":"Gradual rollout to logged in users","parameters":[{"name":"percentage","type":"percentage","description":"What percent of users should the new Feature Toggle be active for?","required":true}]}'
  /admin/metrics/seen-toggles:
    get:
      summary: Returns a list of applications and the feature toggles that Unleash has 'seen' for each application.
@ -596,11 +575,12 @@ paths:
        - Metrics
      responses:
        '200':
-          description: Successful response
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/200seen'
+          $ref: '#/components/responses/seenTogglesResponse'
+      x-code-samples:
+        - lang: 'cURL'
+          source: |
+            curl --request GET \
+              --url http://localhost:4242/api/admin/metrics/seen-toggles
  /admin/metrics/feature-toggles:
    get:
      summary: Gives 'last minute' and 'last hour' metrics for all active feature toggles (based on what was reported by the client applications).
@ -612,17 +592,14 @@ paths:
        - Metrics
      responses:
        '200':
-          description: Successful response
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/200feature'
+          $ref: '#/components/responses/featureAccessResponse'
        '401':
-          description: Not authorized
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/401'
+         $ref: '#/components/responses/notAuthorizedResponse'
+      x-code-samples:
+        - lang: 'cURL'
+          source: |
+            curl --request GET \
+              --url http://localhost:4242/api/admin/metrics/feature-toggles
  /admin/metrics/applications:
    get:
      summary: A list of known applications ('seen' by Unleash in the last two days)
@ -632,17 +609,14 @@ paths:
        - Metrics
      responses:
        '200':
-          description: Successful response
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/applicationArray'
+          $ref: '#/components/responses/applicationsResponse'
        '401':
-          description: Not authorized
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/401'
+          $ref: '#/components/responses/notAuthorizedResponse'
+      x-code-samples:
+        - lang: 'cURL'
+          source: |
+            curl --request GET \
+              --url http://localhost:4242/api/admin/metrics/applications
  '/admin/metrics/applications/{appName}':
    get:
      summary: Details about a client application.
@ -654,19 +628,16 @@ paths:
        - $ref: '#/components/parameters/appNamePath'
      responses:
        '200':
-          description: Successful response
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/200appdetails'
+          $ref: '#/components/responses/appDetailsResponse'
        '401':
-          description: Not authorized
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/401'
+          $ref: '#/components/responses/notAuthorizedResponse'
        '500':
          description: Application name not found
+      x-code-samples:
+        - lang: 'cURL'
+          source: |
+            curl --request GET \
+              --url http://localhost:4242/api/admin/metrics/applications/appName
  /admin/metrics/seen-apps:
    get:
      summary: Details about seen applications
@ -676,17 +647,14 @@ paths:
        - Metrics
      responses:
        '200':
-          description: Successful response
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/applicationArray'
+          $ref: '#/components/responses/applicationsResponse'
        '401':
-          description: Not authorized
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/401'
+          $ref: '#/components/responses/notAuthorizedResponse'
+      x-code-samples:
+        - lang: 'cURL'
+          source: |
+            curl --request GET \
+              --url http://localhost:4242/api/admin/metrics/seen-apps
  /admin/events:
    get:
      operationId: get-admin-events
@ -703,17 +671,14 @@ paths:
        - Events
      responses:
        '200':
-          description: OK
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/200-events'
+          $ref: '#/components/responses/eventsResponse'
        '401':
-          description: Not authorized
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/401'
+          $ref: '#/components/responses/notAuthorizedResponse'
+      x-code-samples:
+        - lang: 'cURL'
+          source: |
+            curl --request GET \
+              --url http://localhost:4242/api/admin/events
  /admin/state/export:
    get:
      operationId: get-admin-state-export
@ -755,17 +720,14 @@ paths:
          example: true
      responses:
        '200':
-          description: OK
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/200export'
+          $ref: '#/components/responses/exportResponse'
        '401':
-          description: Not authorized
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/401'
+          $ref: '#/components/responses/notAuthorizedResponse'
+      x-code-samples:
+        - lang: 'cURL'
+          source: |
+            curl --request GET \
+              --url http://localhost:4242/api/admin/state/export
  /admin/state/import:
    post:
      summary: Import feature toggles and strategies
@ -812,13 +774,15 @@ paths:
        '200':
          description: Successful import.
        '401':
-          description: Not authorized
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/401'
+          $ref: '#/components/responses/notAuthorizedResponse'
        '404':
          description: No import data provided.
+      x-code-samples:
+        - lang: 'cURL'
+          source: |
+            curl --request POST \
+              --url 'http://localhost:4242/api/admin/state/import?drop=false&keep=false' \
+              --data '{"fileName":"string"}'
  /admin/feature-types:
    get:
      summary: Fetch the list of Unleash feature types
@ -833,17 +797,14 @@ paths:
        - Feature types
      responses:
        '200':
-          description: OK
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/200featuretype'
+          $ref: '#/components/responses/featureTypeResponse'
        '401':
-          description: Not authorized
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/401'
+          $ref: '#/components/responses/notAuthorizedResponse'
+      x-code-samples:
+        - lang: 'cURL'
+          source: |
+            curl --request GET \
+              --url http://localhost:4242/api/admin/feature-types
 components:
  parameters:
    featureNamePath:
@ -870,9 +831,81 @@ components:
      example: my-application
      schema:
        type: string
+  responses:
+    successResponse:
+      description: "Successful response"
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/200'
+    notAuthorizedResponse:
+      description: "Not authorized"
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/401'
+    clientResponse:
+      description: "Successful response"
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/200Client'
+    strategyExistsResponse:
+      description: "Strategy already exists"
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/409'
+    strategyResponse:
+      description: "Successful response"
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/200strategy'
+    seenTogglesResponse:
+      description: "Successful response"
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/200seen'
+    featureAccessResponse:
+      description: "Successful response"
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/200feature'
+    appDetailsResponse:
+      description: "Successful response"
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/200appdetails'
+    applicationsResponse:
+      description: "Successful response"
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/applicationArray'
+    eventsResponse:
+      description: "Successful response"
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/200-events'
+    exportResponse:
+      description: "Successful response"
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/200export'
+    featureTypeResponse:
+      description: "Successful response"
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/200featuretype'
  schemas:
    '200':
-      title: Successful response
      type: object
      properties:
        version:
@ -882,7 +915,6 @@ components:
      x-tags:
        - Responses
    '401':
-      description: Not authorized
      type: object
      properties:
        type:
@ -1382,7 +1414,7 @@ components:
      x-tags:
        - Schemas

-    200client:
+    200Client:
      type: object
      properties:
        version: