From acffa17027b68799e5147a1a8a5598f8ca436b1b Mon Sep 17 00:00:00 2001
From: ivgo <ivgo@spreadgroup.com>
Date: Mon, 28 Aug 2023 09:10:21 +0200
Subject: [PATCH] Add examples to openapi definition

Signed-off-by: ivgo <ivgo@spreadgroup.com>
---
 .changeset/polite-plums-share.md              |  5 ++
 .../src/schema/openapi.generated.ts           | 50 +++++++++++++++++++
 .../catalog-backend/src/schema/openapi.yaml   | 30 +++++++++++
 3 files changed, 85 insertions(+)
 create mode 100644 .changeset/polite-plums-share.md

diff --git a/.changeset/polite-plums-share.md b/.changeset/polite-plums-share.md
new file mode 100644
index 0000000000..09c980b921
--- /dev/null
+++ b/.changeset/polite-plums-share.md
@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-catalog-backend': patch
+---
+
+Added some examples to the catalog OpenAPI definition
diff --git a/plugins/catalog-backend/src/schema/openapi.generated.ts b/plugins/catalog-backend/src/schema/openapi.generated.ts
index 001330d59f..2278a30e62 100644
--- a/plugins/catalog-backend/src/schema/openapi.generated.ts
+++ b/plugins/catalog-backend/src/schema/openapi.generated.ts
@@ -111,6 +111,14 @@ export const spec = {
             type: 'string',
           },
         },
+        examples: {
+          'Get name and the entire relations collection': {
+            value: ['metadata.name', 'relations'],
+          },
+          'Get kind, name and namespace': {
+            value: ['kind', 'metadata.name', 'metadata.namespace'],
+          },
+        },
       },
       filter: {
         name: 'filter',
@@ -124,6 +132,16 @@ export const spec = {
             type: 'string',
           },
         },
+        examples: {
+          'Get groups': {
+            value: ['kind=group'],
+          },
+          'Get orphaned components': {
+            value: [
+              'kind=component,metadata.annotations.backstage.io/orphan=true',
+            ],
+          },
+        },
       },
       offset: {
         name: 'offset',
@@ -162,6 +180,14 @@ export const spec = {
         },
         explode: true,
         style: 'form',
+        examples: {
+          'Order ascending by name': {
+            value: ['metadata.name,asc'],
+          },
+          'Order descending by owner': {
+            value: ['spec.owner,desc'],
+          },
+        },
       },
     },
     requestBodies: {},
@@ -1010,6 +1036,22 @@ export const spec = {
                   },
                 },
               },
+              examples: {
+                'Fetch Backstage entities': {
+                  value: {
+                    entityRefs: [
+                      'component:default/backstage',
+                      'api:default/backstage',
+                    ],
+                  },
+                },
+                'Fetch annotations for backstage entity': {
+                  value: {
+                    entityRefs: ['component:default/backstage'],
+                    fields: ['metadata.annotations'],
+                  },
+                },
+              },
             },
           },
         },
@@ -1116,6 +1158,14 @@ export const spec = {
                 type: 'string',
               },
             },
+            examples: {
+              'Entities by kind': {
+                value: ['kind'],
+              },
+              'Entities by spec type': {
+                value: ['spec.type'],
+              },
+            },
           },
           {
             $ref: '#/components/parameters/filter',
diff --git a/plugins/catalog-backend/src/schema/openapi.yaml b/plugins/catalog-backend/src/schema/openapi.yaml
index bad91c8938..4db3147a97 100644
--- a/plugins/catalog-backend/src/schema/openapi.yaml
+++ b/plugins/catalog-backend/src/schema/openapi.yaml
@@ -72,6 +72,11 @@ components:
         type: array
         items:
           type: string
+      examples:
+        'Get name and the entire relations collection':
+          value: ['metadata.name', 'relations']
+        'Get kind, name and namespace':
+          value: ['kind', 'metadata.name', 'metadata.namespace']
     filter:
       name: filter
       in: query
@@ -82,6 +87,12 @@ components:
         type: array
         items:
           type: string
+      examples:
+        'Get groups':
+          value: ['kind=group']
+        'Get orphaned components':
+          value:
+            ['kind=component,metadata.annotations.backstage.io/orphan=true']
     offset:
       name: offset
       in: query
@@ -113,6 +124,11 @@ components:
           description: A two-item tuple of [field, order].
       explode: true
       style: form
+      examples:
+        'Order ascending by name':
+          value: ['metadata.name,asc']
+        'Order descending by owner':
+          value: ['spec.owner,desc']
   requestBodies: {}
   responses: {}
   schemas:
@@ -781,6 +797,15 @@ paths:
                   type: array
                   items:
                     type: string
+            examples:
+              'Fetch Backstage entities':
+                value:
+                  entityRefs:
+                    ['component:default/backstage', 'api:default/backstage']
+              'Fetch annotations for backstage entity':
+                value:
+                  entityRefs: ['component:default/backstage']
+                  fields: ['metadata.annotations']
   /entities/by-query:
     get:
       operationId: GetEntitiesByQuery
@@ -842,6 +867,11 @@ paths:
             type: array
             items:
               type: string
+          examples:
+            'Entities by kind':
+              value: ['kind']
+            'Entities by spec type':
+              value: ['spec.type']
         - $ref: '#/components/parameters/filter'
   /locations:
     post: