diff --git a/microsite/docusaurus.config.ts b/microsite/docusaurus.config.ts index 0f191683c0..86bb05b75d 100644 --- a/microsite/docusaurus.config.ts +++ b/microsite/docusaurus.config.ts @@ -59,7 +59,7 @@ const defaultOpenApiOptions = { hideSendButton: true, sidebarOptions: { groupPathsBy: 'tag', - categoryLinkSource: "tag", + categoryLinkSource: 'tag' }, } satisfies OpenApiPlugin.Options diff --git a/packages/catalog-client/src/schema/openapi/generated/apis/Api.client.ts b/packages/catalog-client/src/schema/openapi/generated/apis/Api.client.ts index 1bf554672c..f605fbd625 100644 --- a/packages/catalog-client/src/schema/openapi/generated/apis/Api.client.ts +++ b/packages/catalog-client/src/schema/openapi/generated/apis/Api.client.ts @@ -22,20 +22,20 @@ import { FetchApi } from '../types/fetch'; import crossFetch from 'cross-fetch'; import { pluginId } from '../pluginId'; import * as parser from 'uri-template'; -import { AnalyzeLocationRequest } from '../models/AnalyzeLocationRequest.model'; -import { AnalyzeLocationResponse } from '../models/AnalyzeLocationResponse.model'; -import { CreateLocation201Response } from '../models/CreateLocation201Response.model'; -import { CreateLocationRequest } from '../models/CreateLocationRequest.model'; import { EntitiesBatchResponse } from '../models/EntitiesBatchResponse.model'; import { EntitiesQueryResponse } from '../models/EntitiesQueryResponse.model'; import { Entity } from '../models/Entity.model'; import { EntityAncestryResponse } from '../models/EntityAncestryResponse.model'; import { EntityFacetsResponse } from '../models/EntityFacetsResponse.model'; import { GetEntitiesByRefsRequest } from '../models/GetEntitiesByRefsRequest.model'; -import { GetLocations200ResponseInner } from '../models/GetLocations200ResponseInner.model'; -import { Location } from '../models/Location.model'; import { RefreshEntityRequest } from '../models/RefreshEntityRequest.model'; import { ValidateEntityRequest } from '../models/ValidateEntityRequest.model'; +import { AnalyzeLocationRequest } from '../models/AnalyzeLocationRequest.model'; +import { AnalyzeLocationResponse } from '../models/AnalyzeLocationResponse.model'; +import { CreateLocation201Response } from '../models/CreateLocation201Response.model'; +import { CreateLocationRequest } from '../models/CreateLocationRequest.model'; +import { GetLocations200ResponseInner } from '../models/GetLocations200ResponseInner.model'; +import { Location } from '../models/Location.model'; /** * Wraps the Response type to convey a type on the json call. @@ -54,21 +54,6 @@ export type TypedResponse = Omit & { export interface RequestOptions { token?: string; } -/** - * @public - */ -export type AnalyzeLocation = { - body: AnalyzeLocationRequest; -}; -/** - * @public - */ -export type CreateLocation = { - body: CreateLocationRequest; - query: { - dryRun?: string; - }; -}; /** * @public */ @@ -77,14 +62,6 @@ export type DeleteEntityByUid = { uid: string; }; }; -/** - * @public - */ -export type DeleteLocation = { - path: { - id: string; - }; -}; /** * @public */ @@ -159,6 +136,41 @@ export type GetEntityFacets = { filter?: Array; }; }; +/** + * @public + */ +export type RefreshEntity = { + body: RefreshEntityRequest; +}; +/** + * @public + */ +export type ValidateEntity = { + body: ValidateEntityRequest; +}; +/** + * @public + */ +export type AnalyzeLocation = { + body: AnalyzeLocationRequest; +}; +/** + * @public + */ +export type CreateLocation = { + body: CreateLocationRequest; + query: { + dryRun?: string; + }; +}; +/** + * @public + */ +export type DeleteLocation = { + path: { + id: string; + }; +}; /** * @public */ @@ -181,18 +193,6 @@ export type GetLocationByEntity = { * @public */ export type GetLocations = {}; -/** - * @public - */ -export type RefreshEntity = { - body: RefreshEntityRequest; -}; -/** - * @public - */ -export type ValidateEntity = { - body: ValidateEntityRequest; -}; /** * @public @@ -209,59 +209,6 @@ export class DefaultApiClient { this.fetchApi = options.fetchApi || { fetch: crossFetch }; } - /** - * Validate a given location. - * @param analyzeLocationRequest - - */ - public async analyzeLocation( - // @ts-ignore - request: AnalyzeLocation, - options?: RequestOptions, - ): Promise> { - const baseUrl = await this.discoveryApi.getBaseUrl(pluginId); - - const uriTemplate = `/analyze-location`; - - const uri = parser.parse(uriTemplate).expand({}); - - return await this.fetchApi.fetch(`${baseUrl}${uri}`, { - headers: { - 'Content-Type': 'application/json', - ...(options?.token && { Authorization: `Bearer ${options?.token}` }), - }, - method: 'POST', - body: JSON.stringify(request.body), - }); - } - - /** - * Create a location for a given target. - * @param createLocationRequest - - * @param dryRun - - */ - public async createLocation( - // @ts-ignore - request: CreateLocation, - options?: RequestOptions, - ): Promise> { - const baseUrl = await this.discoveryApi.getBaseUrl(pluginId); - - const uriTemplate = `/locations{?dryRun}`; - - const uri = parser.parse(uriTemplate).expand({ - ...request.query, - }); - - return await this.fetchApi.fetch(`${baseUrl}${uri}`, { - headers: { - 'Content-Type': 'application/json', - ...(options?.token && { Authorization: `Bearer ${options?.token}` }), - }, - method: 'POST', - body: JSON.stringify(request.body), - }); - } - /** * Delete a single entity by UID. * @param uid - @@ -288,37 +235,11 @@ export class DefaultApiClient { }); } - /** - * Delete a location by id. - * @param id - - */ - public async deleteLocation( - // @ts-ignore - request: DeleteLocation, - options?: RequestOptions, - ): Promise> { - const baseUrl = await this.discoveryApi.getBaseUrl(pluginId); - - const uriTemplate = `/locations/{id}`; - - const uri = parser.parse(uriTemplate).expand({ - id: request.path.id, - }); - - return await this.fetchApi.fetch(`${baseUrl}${uri}`, { - headers: { - 'Content-Type': 'application/json', - ...(options?.token && { Authorization: `Bearer ${options?.token}` }), - }, - method: 'DELETE', - }); - } - /** * Get all entities matching a given filter. - * @param fields - Restrict to just these fields in the response. + * @param fields - By default the full entities are returned, but you can pass in a `fields` query parameter which selects what parts of the entity data to retain. This makes the response smaller and faster to transfer, and may allow the catalog to perform more efficient queries. The query parameter value is a comma separated list of simplified JSON paths like above. Each path corresponds to the key of either a value, or of a subtree root that you want to keep in the output. The rest is pruned away. For example, specifying `?fields=metadata.name,metadata.annotations,spec` retains only the `name` and `annotations` fields of the `metadata` of each entity (it'll be an object with at most two keys), keeps the entire `spec` unchanged, and cuts out all other roots such as `relations`. Some more real world usable examples: - Return only enough data to form the full ref of each entity: `/entities/by-query?fields=kind,metadata.namespace,metadata.name` * @param limit - Number of records to return in the response. - * @param filter - Filter for just the entities defined by this filter. + * @param filter - You can pass in one or more filter sets that get matched against each entity. Each filter set is a number of conditions that all have to match for the condition to be true (conditions effectively have an AND between them). At least one filter set has to be true for the entity to be part of the result set (filter sets effectively have an OR between them). Example: ```text /entities/by-query?filter=kind=user,metadata.namespace=default&filter=kind=group,spec.type Return entities that match Filter set 1: Condition 1: kind = user AND Condition 2: metadata.namespace = default OR Filter set 2: Condition 1: kind = group AND Condition 2: spec.type exists ``` Each condition is either on the form `<key>`, or on the form `<key>=<value>`. The first form asserts on the existence of a certain key (with any value), and the second asserts that the key exists and has a certain value. All checks are always case _insensitive_. In all cases, the key is a simplified JSON path in a given piece of entity data. Each part of the path is a key of an object, and the traversal also descends through arrays. There are two special forms: - Array items that are simple value types (such as strings) match on a key-value pair where the key is the item as a string, and the value is the string `true` - Relations can be matched on a `relations.<type>=<targetRef>` form Let's look at a simplified example to illustrate the concept: ```json { \"a\": { \"b\": [\"c\", { \"d\": 1 }], \"e\": 7 } } ``` This would match any one of the following conditions: - `a` - `a.b` - `a.b.c` - `a.b.c=true` - `a.b.d` - `a.b.d=1` - `a.e` - `a.e=7` Some more real world usable examples: - Return all orphaned entities: `/entities/by-query?filter=metadata.annotations.backstage.io/orphan=true` - Return all users and groups: `/entities/by-query?filter=kind=user&filter=kind=group` - Return all service components: `/entities/by-query?filter=kind=component,spec.type=service` - Return all entities with the `java` tag: `/entities/by-query?filter=metadata.tags.java` - Return all users who are members of the `ops` group (note that the full [reference](references.md) of the group is used): `/entities/by-query?filter=kind=user,relations.memberof=group:default/ops` * @param offset - Number of records to skip in the query page. * @param after - Pointer to the previous page of results. * @param order - @@ -347,12 +268,12 @@ export class DefaultApiClient { /** * Search for entities by a given query. - * @param fields - Restrict to just these fields in the response. + * @param fields - By default the full entities are returned, but you can pass in a `fields` query parameter which selects what parts of the entity data to retain. This makes the response smaller and faster to transfer, and may allow the catalog to perform more efficient queries. The query parameter value is a comma separated list of simplified JSON paths like above. Each path corresponds to the key of either a value, or of a subtree root that you want to keep in the output. The rest is pruned away. For example, specifying `?fields=metadata.name,metadata.annotations,spec` retains only the `name` and `annotations` fields of the `metadata` of each entity (it'll be an object with at most two keys), keeps the entire `spec` unchanged, and cuts out all other roots such as `relations`. Some more real world usable examples: - Return only enough data to form the full ref of each entity: `/entities/by-query?fields=kind,metadata.namespace,metadata.name` * @param limit - Number of records to return in the response. * @param offset - Number of records to skip in the query page. - * @param orderField - The fields to sort returned results by. - * @param cursor - Cursor to a set page of results. - * @param filter - Filter for just the entities defined by this filter. + * @param orderField - By default the entities are returned ordered by their internal uid. You can customize the `orderField` query parameters to affect that ordering. For example, to return entities by their name: `/entities/by-query?orderField=metadata.name,asc` Each parameter can be followed by `asc` for ascending lexicographical order or `desc` for descending (reverse) lexicographical order. + * @param cursor - You may pass the `cursor` query parameters to perform cursor based pagination through the set of entities. The value of `cursor` will be returned in the response, under the `pageInfo` property: ```json \"pageInfo\": { \"nextCursor\": \"a-cursor\", \"prevCursor\": \"another-cursor\" } ``` If `nextCursor` exists, it can be used to retrieve the next batch of entities. Following the same approach, if `prevCursor` exists, it can be used to retrieve the previous batch of entities. - [`filter`](#filtering), for selecting only a subset of all entities - [`fields`](#field-selection), for selecting only parts of the full data structure of each entity - `limit` for limiting the number of entities returned (20 is the default) - [`orderField`](#ordering), for deciding the order of the entities - `fullTextFilter` **NOTE**: [`filter`, `orderField`, `fullTextFilter`] and `cursor` are mutually exclusive. This means that, it isn't possible to change any of [`filter`, `orderField`, `fullTextFilter`] when passing `cursor` as query parameters, as changing any of these properties will affect pagination. If any of `filter`, `orderField`, `fullTextFilter` is specified together with `cursor`, only the latter is taken into consideration. + * @param filter - You can pass in one or more filter sets that get matched against each entity. Each filter set is a number of conditions that all have to match for the condition to be true (conditions effectively have an AND between them). At least one filter set has to be true for the entity to be part of the result set (filter sets effectively have an OR between them). Example: ```text /entities/by-query?filter=kind=user,metadata.namespace=default&filter=kind=group,spec.type Return entities that match Filter set 1: Condition 1: kind = user AND Condition 2: metadata.namespace = default OR Filter set 2: Condition 1: kind = group AND Condition 2: spec.type exists ``` Each condition is either on the form `<key>`, or on the form `<key>=<value>`. The first form asserts on the existence of a certain key (with any value), and the second asserts that the key exists and has a certain value. All checks are always case _insensitive_. In all cases, the key is a simplified JSON path in a given piece of entity data. Each part of the path is a key of an object, and the traversal also descends through arrays. There are two special forms: - Array items that are simple value types (such as strings) match on a key-value pair where the key is the item as a string, and the value is the string `true` - Relations can be matched on a `relations.<type>=<targetRef>` form Let's look at a simplified example to illustrate the concept: ```json { \"a\": { \"b\": [\"c\", { \"d\": 1 }], \"e\": 7 } } ``` This would match any one of the following conditions: - `a` - `a.b` - `a.b.c` - `a.b.c=true` - `a.b.d` - `a.b.d=1` - `a.e` - `a.e=7` Some more real world usable examples: - Return all orphaned entities: `/entities/by-query?filter=metadata.annotations.backstage.io/orphan=true` - Return all users and groups: `/entities/by-query?filter=kind=user&filter=kind=group` - Return all service components: `/entities/by-query?filter=kind=component,spec.type=service` - Return all entities with the `java` tag: `/entities/by-query?filter=metadata.tags.java` - Return all users who are members of the `ops` group (note that the full [reference](references.md) of the group is used): `/entities/by-query?filter=kind=user,relations.memberof=group:default/ops` * @param fullTextFilterTerm - Text search term. * @param fullTextFilterFields - A comma separated list of fields to sort returned results by. */ @@ -380,7 +301,7 @@ export class DefaultApiClient { /** * Get a batch set of entities given an array of entityRefs. - * @param filter - Filter for just the entities defined by this filter. + * @param filter - You can pass in one or more filter sets that get matched against each entity. Each filter set is a number of conditions that all have to match for the condition to be true (conditions effectively have an AND between them). At least one filter set has to be true for the entity to be part of the result set (filter sets effectively have an OR between them). Example: ```text /entities/by-query?filter=kind=user,metadata.namespace=default&filter=kind=group,spec.type Return entities that match Filter set 1: Condition 1: kind = user AND Condition 2: metadata.namespace = default OR Filter set 2: Condition 1: kind = group AND Condition 2: spec.type exists ``` Each condition is either on the form `<key>`, or on the form `<key>=<value>`. The first form asserts on the existence of a certain key (with any value), and the second asserts that the key exists and has a certain value. All checks are always case _insensitive_. In all cases, the key is a simplified JSON path in a given piece of entity data. Each part of the path is a key of an object, and the traversal also descends through arrays. There are two special forms: - Array items that are simple value types (such as strings) match on a key-value pair where the key is the item as a string, and the value is the string `true` - Relations can be matched on a `relations.<type>=<targetRef>` form Let's look at a simplified example to illustrate the concept: ```json { \"a\": { \"b\": [\"c\", { \"d\": 1 }], \"e\": 7 } } ``` This would match any one of the following conditions: - `a` - `a.b` - `a.b.c` - `a.b.c=true` - `a.b.d` - `a.b.d=1` - `a.e` - `a.e=7` Some more real world usable examples: - Return all orphaned entities: `/entities/by-query?filter=metadata.annotations.backstage.io/orphan=true` - Return all users and groups: `/entities/by-query?filter=kind=user&filter=kind=group` - Return all service components: `/entities/by-query?filter=kind=component,spec.type=service` - Return all entities with the `java` tag: `/entities/by-query?filter=metadata.tags.java` - Return all users who are members of the `ops` group (note that the full [reference](references.md) of the group is used): `/entities/by-query?filter=kind=user,relations.memberof=group:default/ops` * @param getEntitiesByRefsRequest - */ public async getEntitiesByRefs( @@ -495,7 +416,7 @@ export class DefaultApiClient { /** * Get all entity facets that match the given filters. * @param facet - - * @param filter - Filter for just the entities defined by this filter. + * @param filter - You can pass in one or more filter sets that get matched against each entity. Each filter set is a number of conditions that all have to match for the condition to be true (conditions effectively have an AND between them). At least one filter set has to be true for the entity to be part of the result set (filter sets effectively have an OR between them). Example: ```text /entities/by-query?filter=kind=user,metadata.namespace=default&filter=kind=group,spec.type Return entities that match Filter set 1: Condition 1: kind = user AND Condition 2: metadata.namespace = default OR Filter set 2: Condition 1: kind = group AND Condition 2: spec.type exists ``` Each condition is either on the form `<key>`, or on the form `<key>=<value>`. The first form asserts on the existence of a certain key (with any value), and the second asserts that the key exists and has a certain value. All checks are always case _insensitive_. In all cases, the key is a simplified JSON path in a given piece of entity data. Each part of the path is a key of an object, and the traversal also descends through arrays. There are two special forms: - Array items that are simple value types (such as strings) match on a key-value pair where the key is the item as a string, and the value is the string `true` - Relations can be matched on a `relations.<type>=<targetRef>` form Let's look at a simplified example to illustrate the concept: ```json { \"a\": { \"b\": [\"c\", { \"d\": 1 }], \"e\": 7 } } ``` This would match any one of the following conditions: - `a` - `a.b` - `a.b.c` - `a.b.c=true` - `a.b.d` - `a.b.d=1` - `a.e` - `a.e=7` Some more real world usable examples: - Return all orphaned entities: `/entities/by-query?filter=metadata.annotations.backstage.io/orphan=true` - Return all users and groups: `/entities/by-query?filter=kind=user&filter=kind=group` - Return all service components: `/entities/by-query?filter=kind=component,spec.type=service` - Return all entities with the `java` tag: `/entities/by-query?filter=metadata.tags.java` - Return all users who are members of the `ops` group (note that the full [reference](references.md) of the group is used): `/entities/by-query?filter=kind=user,relations.memberof=group:default/ops` */ public async getEntityFacets( // @ts-ignore @@ -519,6 +440,135 @@ export class DefaultApiClient { }); } + /** + * Refresh the entity related to entityRef. + * @param refreshEntityRequest - + */ + public async refreshEntity( + // @ts-ignore + request: RefreshEntity, + options?: RequestOptions, + ): Promise> { + const baseUrl = await this.discoveryApi.getBaseUrl(pluginId); + + const uriTemplate = `/refresh`; + + const uri = parser.parse(uriTemplate).expand({}); + + return await this.fetchApi.fetch(`${baseUrl}${uri}`, { + headers: { + 'Content-Type': 'application/json', + ...(options?.token && { Authorization: `Bearer ${options?.token}` }), + }, + method: 'POST', + body: JSON.stringify(request.body), + }); + } + + /** + * Validate that a passed in entity has no errors in schema. + * @param validateEntityRequest - + */ + public async validateEntity( + // @ts-ignore + request: ValidateEntity, + options?: RequestOptions, + ): Promise> { + const baseUrl = await this.discoveryApi.getBaseUrl(pluginId); + + const uriTemplate = `/validate-entity`; + + const uri = parser.parse(uriTemplate).expand({}); + + return await this.fetchApi.fetch(`${baseUrl}${uri}`, { + headers: { + 'Content-Type': 'application/json', + ...(options?.token && { Authorization: `Bearer ${options?.token}` }), + }, + method: 'POST', + body: JSON.stringify(request.body), + }); + } + + /** + * Validate a given location. + * @param analyzeLocationRequest - + */ + public async analyzeLocation( + // @ts-ignore + request: AnalyzeLocation, + options?: RequestOptions, + ): Promise> { + const baseUrl = await this.discoveryApi.getBaseUrl(pluginId); + + const uriTemplate = `/analyze-location`; + + const uri = parser.parse(uriTemplate).expand({}); + + return await this.fetchApi.fetch(`${baseUrl}${uri}`, { + headers: { + 'Content-Type': 'application/json', + ...(options?.token && { Authorization: `Bearer ${options?.token}` }), + }, + method: 'POST', + body: JSON.stringify(request.body), + }); + } + + /** + * Create a location for a given target. + * @param createLocationRequest - + * @param dryRun - + */ + public async createLocation( + // @ts-ignore + request: CreateLocation, + options?: RequestOptions, + ): Promise> { + const baseUrl = await this.discoveryApi.getBaseUrl(pluginId); + + const uriTemplate = `/locations{?dryRun}`; + + const uri = parser.parse(uriTemplate).expand({ + ...request.query, + }); + + return await this.fetchApi.fetch(`${baseUrl}${uri}`, { + headers: { + 'Content-Type': 'application/json', + ...(options?.token && { Authorization: `Bearer ${options?.token}` }), + }, + method: 'POST', + body: JSON.stringify(request.body), + }); + } + + /** + * Delete a location by id. + * @param id - + */ + public async deleteLocation( + // @ts-ignore + request: DeleteLocation, + options?: RequestOptions, + ): Promise> { + const baseUrl = await this.discoveryApi.getBaseUrl(pluginId); + + const uriTemplate = `/locations/{id}`; + + const uri = parser.parse(uriTemplate).expand({ + id: request.path.id, + }); + + return await this.fetchApi.fetch(`${baseUrl}${uri}`, { + headers: { + 'Content-Type': 'application/json', + ...(options?.token && { Authorization: `Bearer ${options?.token}` }), + }, + method: 'DELETE', + }); + } + /** * Get a location by id. * @param id - @@ -597,54 +647,4 @@ export class DefaultApiClient { method: 'GET', }); } - - /** - * Refresh the entity related to entityRef. - * @param refreshEntityRequest - - */ - public async refreshEntity( - // @ts-ignore - request: RefreshEntity, - options?: RequestOptions, - ): Promise> { - const baseUrl = await this.discoveryApi.getBaseUrl(pluginId); - - const uriTemplate = `/refresh`; - - const uri = parser.parse(uriTemplate).expand({}); - - return await this.fetchApi.fetch(`${baseUrl}${uri}`, { - headers: { - 'Content-Type': 'application/json', - ...(options?.token && { Authorization: `Bearer ${options?.token}` }), - }, - method: 'POST', - body: JSON.stringify(request.body), - }); - } - - /** - * Validate that a passed in entity has no errors in schema. - * @param validateEntityRequest - - */ - public async validateEntity( - // @ts-ignore - request: ValidateEntity, - options?: RequestOptions, - ): Promise> { - const baseUrl = await this.discoveryApi.getBaseUrl(pluginId); - - const uriTemplate = `/validate-entity`; - - const uri = parser.parse(uriTemplate).expand({}); - - return await this.fetchApi.fetch(`${baseUrl}${uri}`, { - headers: { - 'Content-Type': 'application/json', - ...(options?.token && { Authorization: `Bearer ${options?.token}` }), - }, - method: 'POST', - body: JSON.stringify(request.body), - }); - } } diff --git a/plugins/catalog-backend/src/schema/openapi/generated/apis/Api.server.ts b/plugins/catalog-backend/src/schema/openapi/generated/apis/Api.server.ts index abd73e2876..b758377e5f 100644 --- a/plugins/catalog-backend/src/schema/openapi/generated/apis/Api.server.ts +++ b/plugins/catalog-backend/src/schema/openapi/generated/apis/Api.server.ts @@ -19,39 +19,16 @@ // ****************************************************************** // * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY. * // ****************************************************************** -import { AnalyzeLocationRequest } from '../models/AnalyzeLocationRequest.model'; -import { AnalyzeLocationResponse } from '../models/AnalyzeLocationResponse.model'; -import { CreateLocation201Response } from '../models/CreateLocation201Response.model'; -import { CreateLocationRequest } from '../models/CreateLocationRequest.model'; import { EntitiesBatchResponse } from '../models/EntitiesBatchResponse.model'; import { EntitiesQueryResponse } from '../models/EntitiesQueryResponse.model'; import { Entity } from '../models/Entity.model'; import { EntityAncestryResponse } from '../models/EntityAncestryResponse.model'; import { EntityFacetsResponse } from '../models/EntityFacetsResponse.model'; import { GetEntitiesByRefsRequest } from '../models/GetEntitiesByRefsRequest.model'; -import { GetLocations200ResponseInner } from '../models/GetLocations200ResponseInner.model'; -import { Location } from '../models/Location.model'; import { RefreshEntityRequest } from '../models/RefreshEntityRequest.model'; import { ValidateEntity400Response } from '../models/ValidateEntity400Response.model'; import { ValidateEntityRequest } from '../models/ValidateEntityRequest.model'; -/** - * @public - */ -export type AnalyzeLocation = { - body: AnalyzeLocationRequest; - response: AnalyzeLocationResponse | Error | Error; -}; -/** - * @public - */ -export type CreateLocation = { - body: CreateLocationRequest; - query: { - dryRun?: string; - }; - response: CreateLocation201Response | Error | Error; -}; /** * @public */ @@ -61,15 +38,6 @@ export type DeleteEntityByUid = { }; response: void | Error | Error; }; -/** - * @public - */ -export type DeleteLocation = { - path: { - id: string; - }; - response: void | Error | Error; -}; /** * @public */ @@ -151,6 +119,53 @@ export type GetEntityFacets = { }; response: EntityFacetsResponse | Error | Error; }; +/** + * @public + */ +export type RefreshEntity = { + body: RefreshEntityRequest; + response: void | Error | Error; +}; +/** + * @public + */ +export type ValidateEntity = { + body: ValidateEntityRequest; + response: void | ValidateEntity400Response; +}; +import { AnalyzeLocationRequest } from '../models/AnalyzeLocationRequest.model'; +import { AnalyzeLocationResponse } from '../models/AnalyzeLocationResponse.model'; +import { CreateLocation201Response } from '../models/CreateLocation201Response.model'; +import { CreateLocationRequest } from '../models/CreateLocationRequest.model'; +import { GetLocations200ResponseInner } from '../models/GetLocations200ResponseInner.model'; +import { Location } from '../models/Location.model'; + +/** + * @public + */ +export type AnalyzeLocation = { + body: AnalyzeLocationRequest; + response: AnalyzeLocationResponse | Error | Error; +}; +/** + * @public + */ +export type CreateLocation = { + body: CreateLocationRequest; + query: { + dryRun?: string; + }; + response: CreateLocation201Response | Error | Error; +}; +/** + * @public + */ +export type DeleteLocation = { + path: { + id: string; + }; + response: void | Error | Error; +}; /** * @public */ @@ -177,30 +192,10 @@ export type GetLocationByEntity = { export type GetLocations = { response: Array | Error; }; -/** - * @public - */ -export type RefreshEntity = { - body: RefreshEntityRequest; - response: void | Error | Error; -}; -/** - * @public - */ -export type ValidateEntity = { - body: ValidateEntityRequest; - response: void | ValidateEntity400Response; -}; export type EndpointMap = { - '#post|/analyze-location': AnalyzeLocation; - - '#post|/locations': CreateLocation; - '#_delete|/entities/by-uid/{uid}': DeleteEntityByUid; - '#_delete|/locations/{id}': DeleteLocation; - '#get|/entities': GetEntities; '#get|/entities/by-query': GetEntitiesByQuery; @@ -215,13 +210,19 @@ export type EndpointMap = { '#get|/entity-facets': GetEntityFacets; + '#post|/refresh': RefreshEntity; + + '#post|/validate-entity': ValidateEntity; + + '#post|/analyze-location': AnalyzeLocation; + + '#post|/locations': CreateLocation; + + '#_delete|/locations/{id}': DeleteLocation; + '#get|/locations/{id}': GetLocation; '#get|/locations/by-entity/{kind}/{namespace}/{name}': GetLocationByEntity; '#get|/locations': GetLocations; - - '#post|/refresh': RefreshEntity; - - '#post|/validate-entity': ValidateEntity; }; diff --git a/plugins/catalog-backend/src/schema/openapi/generated/router.ts b/plugins/catalog-backend/src/schema/openapi/generated/router.ts index 8712625653..67eb1a699e 100644 --- a/plugins/catalog-backend/src/schema/openapi/generated/router.ts +++ b/plugins/catalog-backend/src/schema/openapi/generated/router.ts @@ -26,7 +26,7 @@ export const spec = { title: 'catalog', version: '1', description: - 'The Backstage backend plugin that provides the Backstage catalog', + 'The API surface consists of a few distinct groups of functionality. Each has a\ndedicated section below.\n\n> **Note:** This page only describes some of the most commonly used parts of the\n> API, and is a work in progress.\n\nAll of the URL paths in this article are assumed to be on top of some base URL\npointing at your catalog installation. For example, if the path given in a\nsection below is `/entities`, and the catalog is located at\n`http://localhost:7007/api/catalog` during local development, the full URL would\nbe `http://localhost:7007/api/catalog/entities`. The actual URL may vary from\none organization to the other, especially in production, but is commonly your\n`backend.baseUrl` in your app config, plus `/api/catalog` at the end.\n\nSome or all of the endpoints may accept or require an `Authorization` header\nwith a `Bearer` token, which should then be the Backstage token returned by the\n[`identity API`](https://backstage.io/docs/reference/core-plugin-api.identityapiref).\n', license: { name: 'Apache-2.0', url: 'http://www.apache.org/licenses/LICENSE-2.0.html', @@ -81,7 +81,8 @@ export const spec = { cursor: { name: 'cursor', in: 'query', - description: 'Cursor to a set page of results.', + description: + 'You may pass the `cursor` query parameters to perform cursor based pagination\nthrough the set of entities. The value of `cursor` will be returned in the response, under the `pageInfo` property:\n\n```json\n "pageInfo": {\n "nextCursor": "a-cursor",\n "prevCursor": "another-cursor"\n }\n```\n\nIf `nextCursor` exists, it can be used to retrieve the next batch of entities. Following the same approach,\nif `prevCursor` exists, it can be used to retrieve the previous batch of entities.\n\n- [`filter`](#filtering), for selecting only a subset of all entities\n- [`fields`](#field-selection), for selecting only parts of the full data\n structure of each entity\n- `limit` for limiting the number of entities returned (20 is the default)\n- [`orderField`](#ordering), for deciding the order of the entities\n- `fullTextFilter`\n **NOTE**: [`filter`, `orderField`, `fullTextFilter`] and `cursor` are mutually exclusive. This means that,\n it isn\'t possible to change any of [`filter`, `orderField`, `fullTextFilter`] when passing `cursor` as query parameters,\n as changing any of these properties will affect pagination. If any of `filter`, `orderField`, `fullTextFilter` is specified together with `cursor`, only the latter is taken into consideration.\n', required: false, allowReserved: true, schema: { @@ -103,7 +104,8 @@ export const spec = { fields: { name: 'fields', in: 'query', - description: 'Restrict to just these fields in the response.', + description: + "By default the full entities are returned, but you can pass in a `fields` query\nparameter which selects what parts of the entity data to retain. This makes the\nresponse smaller and faster to transfer, and may allow the catalog to perform\nmore efficient queries.\n\nThe query parameter value is a comma separated list of simplified JSON paths\nlike above. Each path corresponds to the key of either a value, or of a subtree\nroot that you want to keep in the output. The rest is pruned away. For example,\nspecifying `?fields=metadata.name,metadata.annotations,spec` retains only the\n`name` and `annotations` fields of the `metadata` of each entity (it'll be an\nobject with at most two keys), keeps the entire `spec` unchanged, and cuts out\nall other roots such as `relations`.\n\nSome more real world usable examples:\n\n- Return only enough data to form the full ref of each entity:\n\n `/entities/by-query?fields=kind,metadata.namespace,metadata.name`\n", required: false, allowReserved: true, explode: false, @@ -125,7 +127,8 @@ export const spec = { filter: { name: 'filter', in: 'query', - description: 'Filter for just the entities defined by this filter.', + description: + 'You can pass in one or more filter sets that get matched against each entity.\nEach filter set is a number of conditions that all have to match for the\ncondition to be true (conditions effectively have an AND between them). At least\none filter set has to be true for the entity to be part of the result set\n(filter sets effectively have an OR between them).\n\nExample:\n\n```text\n/entities/by-query?filter=kind=user,metadata.namespace=default&filter=kind=group,spec.type\n\n Return entities that match\n\n Filter set 1:\n Condition 1: kind = user\n AND\n Condition 2: metadata.namespace = default\n\n OR\n\n Filter set 2:\n Condition 1: kind = group\n AND\n Condition 2: spec.type exists\n```\n\nEach condition is either on the form ``, or on the form `=`.\nThe first form asserts on the existence of a certain key (with any value), and\nthe second asserts that the key exists and has a certain value. All checks are\nalways case _insensitive_.\n\nIn all cases, the key is a simplified JSON path in a given piece of entity data.\nEach part of the path is a key of an object, and the traversal also descends\nthrough arrays. There are two special forms:\n\n- Array items that are simple value types (such as strings) match on a key-value\n pair where the key is the item as a string, and the value is the string `true`\n- Relations can be matched on a `relations.=` form\n\nLet\'s look at a simplified example to illustrate the concept:\n\n```json\n{\n "a": {\n "b": ["c", { "d": 1 }],\n "e": 7\n }\n}\n```\n\nThis would match any one of the following conditions:\n\n- `a`\n- `a.b`\n- `a.b.c`\n- `a.b.c=true`\n- `a.b.d`\n- `a.b.d=1`\n- `a.e`\n- `a.e=7`\n\nSome more real world usable examples:\n\n- Return all orphaned entities:\n\n `/entities/by-query?filter=metadata.annotations.backstage.io/orphan=true`\n\n- Return all users and groups:\n\n `/entities/by-query?filter=kind=user&filter=kind=group`\n\n- Return all service components:\n\n `/entities/by-query?filter=kind=component,spec.type=service`\n\n- Return all entities with the `java` tag:\n\n `/entities/by-query?filter=metadata.tags.java`\n\n- Return all users who are members of the `ops` group (note that the full\n [reference](references.md) of the group is used):\n\n `/entities/by-query?filter=kind=user,relations.memberof=group:default/ops`\n', required: false, allowReserved: true, schema: { @@ -170,7 +173,8 @@ export const spec = { orderField: { name: 'orderField', in: 'query', - description: 'The fields to sort returned results by.', + description: + 'By default the entities are returned ordered by their internal uid. You can\ncustomize the `orderField` query parameters to affect that ordering.\n\nFor example, to return entities by their name:\n\n`/entities/by-query?orderField=metadata.name,asc`\n\nEach parameter can be followed by `asc` for ascending lexicographical order or\n`desc` for descending (reverse) lexicographical order.\n', required: false, allowReserved: true, schema: { @@ -788,6 +792,7 @@ export const spec = { '/refresh': { post: { operationId: 'RefreshEntity', + tags: ['Entity'], description: 'Refresh the entity related to entityRef.', responses: { '200': { @@ -836,6 +841,7 @@ export const spec = { '/entities': { get: { operationId: 'GetEntities', + tags: ['Entity'], description: 'Get all entities matching a given filter.', responses: { '200': { @@ -898,6 +904,7 @@ export const spec = { '/entities/by-uid/{uid}': { get: { operationId: 'GetEntityByUid', + tags: ['Entity'], description: 'Get a single entity by the UID.', responses: { '200': { @@ -931,6 +938,7 @@ export const spec = { }, delete: { operationId: 'DeleteEntityByUid', + tags: ['Entity'], description: 'Delete a single entity by UID.', responses: { '204': { @@ -959,6 +967,7 @@ export const spec = { '/entities/by-name/{kind}/{namespace}/{name}': { get: { operationId: 'GetEntityByName', + tags: ['Entity'], description: 'Get an entity by an entity ref.', responses: { '200': { @@ -1000,6 +1009,7 @@ export const spec = { '/entities/by-name/{kind}/{namespace}/{name}/ancestry': { get: { operationId: 'GetEntityAncestryByName', + tags: ['Entity'], description: "Get an entity's ancestry by entity ref.", responses: { '200': { @@ -1041,6 +1051,7 @@ export const spec = { '/entities/by-refs': { post: { operationId: 'GetEntitiesByRefs', + tags: ['Entity'], description: 'Get a batch set of entities given an array of entityRefs.', responses: { @@ -1118,6 +1129,7 @@ export const spec = { '/entities/by-query': { get: { operationId: 'GetEntitiesByQuery', + tags: ['Entity'], description: 'Search for entities by a given query.', responses: { '200': { @@ -1194,6 +1206,7 @@ export const spec = { '/entity-facets': { get: { operationId: 'GetEntityFacets', + tags: ['Entity'], description: 'Get all entity facets that match the given filters.', responses: { '200': { @@ -1249,6 +1262,7 @@ export const spec = { '/locations': { post: { operationId: 'CreateLocation', + tags: ['Locations'], description: 'Create a location for a given target.', responses: { '201': { @@ -1322,6 +1336,7 @@ export const spec = { }, get: { operationId: 'GetLocations', + tags: ['Locations'], description: 'Get all locations', responses: { '200': { @@ -1359,6 +1374,7 @@ export const spec = { '/locations/{id}': { get: { operationId: 'GetLocation', + tags: ['Locations'], description: 'Get a location by id.', responses: { '200': { @@ -1395,6 +1411,7 @@ export const spec = { }, delete: { operationId: 'DeleteLocation', + tags: ['Locations'], description: 'Delete a location by id.', responses: { '204': { @@ -1429,6 +1446,7 @@ export const spec = { '/locations/by-entity/{kind}/{namespace}/{name}': { get: { operationId: 'getLocationByEntity', + tags: ['Locations'], description: 'Get a location for entity.', responses: { '200': { @@ -1485,6 +1503,7 @@ export const spec = { '/analyze-location': { post: { operationId: 'AnalyzeLocation', + tags: ['Locations'], description: 'Validate a given location.', responses: { '200': { @@ -1535,6 +1554,7 @@ export const spec = { '/validate-entity': { post: { operationId: 'ValidateEntity', + tags: ['Entity'], description: 'Validate that a passed in entity has no errors in schema.', responses: { diff --git a/plugins/search-backend/src/schema/openapi.yaml b/plugins/search-backend/src/schema/openapi.yaml index b1b8e83f58..d0257a7ce0 100644 --- a/plugins/search-backend/src/schema/openapi.yaml +++ b/plugins/search-backend/src/schema/openapi.yaml @@ -72,6 +72,8 @@ paths: get: operationId: Query description: Query documents with a given filter. + tags: + - Search responses: '200': description: Ok