diff --git a/.changeset/large-frogs-grab.md b/.changeset/large-frogs-grab.md new file mode 100644 index 0000000000..2d36de3407 --- /dev/null +++ b/.changeset/large-frogs-grab.md @@ -0,0 +1,5 @@ +--- +'@backstage/plugin-api-docs': patch +--- + +Adding `supportedSubmitMethods` prop to `api-docs` to pass to the Swagger UI. This allows users to specify which HTTP methods they wish to allow end-users to make requests through the `Try It Out` button on the Swagger UI. diff --git a/plugins/api-docs/README.md b/plugins/api-docs/README.md index 4d4342de61..46d9df4628 100644 --- a/plugins/api-docs/README.md +++ b/plugins/api-docs/README.md @@ -263,3 +263,56 @@ createApiFactory({ ``` In the same way as the `requestInterceptor` you can override any property of Swagger UI + +### Provide Specific Supported Methods to Swagger UI + +This can be done through utilising the +[supportedSubmitMethods prop](https://github.com/swagger-api/swagger-ui/tree/master/flavors/swagger-ui-react#supportedsubmitmethods-proptypesarrayofproptypesoneofget-put-post-delete-options-head-patch-trace). +If you wish to limit the HTTP methods available for the `Try It Out` feature of an OpenAPI API +component, you will need to add the following to your `api.tsx`, listing the permitted methods for +your API in the `supportedSubmitMethods` parameter: + +```tsx +... +import { + OpenApiDefinitionWidget, + apiDocsConfigRef, + defaultDefinitionWidgets, +} from '@backstage/plugin-api-docs'; +import { ApiEntity } from '@backstage/catalog-model'; + +export const apis: AnyApiFactory[] = [ +... + createApiFactory({ + api: apiDocsConfigRef, + deps: {}, + factory: () => { + const supportedSubmitMethods = ['get', 'post', 'put', 'delete']; + const definitionWidgets = defaultDefinitionWidgets().map(obj => { + if (obj.type === 'openapi') { + return { + ...obj, + component: definition => ( + + ), + }; + } + return obj; + }); + + return { + getApiDefinitionWidget: (apiEntity: ApiEntity) => { + return definitionWidgets.find(d => d.type === apiEntity.spec.type); + } + }; + } + }) +] + +``` + +N.B. if you wish to disable the `Try It Out` feature for your API, you can provide an empty list to +the `supportedSubmitMethods` parameter. diff --git a/plugins/api-docs/api-report.md b/plugins/api-docs/api-report.md index a018dfcdb1..7523198298 100644 --- a/plugins/api-docs/api-report.md +++ b/plugins/api-docs/api-report.md @@ -166,6 +166,7 @@ export const OpenApiDefinitionWidget: ( export type OpenApiDefinitionWidgetProps = { definition: string; requestInterceptor?: (req: any) => any | Promise; + supportedSubmitMethods?: string[]; }; // @public (undocumented) diff --git a/plugins/api-docs/src/components/OpenApiDefinitionWidget/OpenApiDefinition.test.tsx b/plugins/api-docs/src/components/OpenApiDefinitionWidget/OpenApiDefinition.test.tsx index d150525b05..524c416d2d 100644 --- a/plugins/api-docs/src/components/OpenApiDefinitionWidget/OpenApiDefinition.test.tsx +++ b/plugins/api-docs/src/components/OpenApiDefinitionWidget/OpenApiDefinition.test.tsx @@ -97,11 +97,13 @@ paths: `; const requestInterceptor = (req: any) => req; + const supportedSubmitMethods = ['get', 'post', 'put', 'delete']; const { findByRole, getByRole, getByLabelText } = await renderInTestApp( , ); diff --git a/plugins/api-docs/src/components/OpenApiDefinitionWidget/OpenApiDefinitionWidget.tsx b/plugins/api-docs/src/components/OpenApiDefinitionWidget/OpenApiDefinitionWidget.tsx index 152f1fd089..64ff324941 100644 --- a/plugins/api-docs/src/components/OpenApiDefinitionWidget/OpenApiDefinitionWidget.tsx +++ b/plugins/api-docs/src/components/OpenApiDefinitionWidget/OpenApiDefinitionWidget.tsx @@ -29,15 +29,22 @@ const LazyOpenApiDefinition = React.lazy(() => export type OpenApiDefinitionWidgetProps = { definition: string; requestInterceptor?: (req: any) => any | Promise; + supportedSubmitMethods?: string[]; }; /** @public */ export const OpenApiDefinitionWidget = ( props: OpenApiDefinitionWidgetProps, ) => { + const validSubmitMethods = props.supportedSubmitMethods?.map(method => + method.toLocaleLowerCase(), + ); return ( }> - + ); };