Export apiDocsConfigRef from api-docs plugin to allow extending it with custom API renderers

Signed-off-by: Oliver Sand <oliver.sand@sda-se.com>

.changeset/pink-sloths-nail.md

@@ -0,0 +1,6 @@
+---
+'@backstage/plugin-api-docs': patch
+---
+
+Export `apiDocsConfigRef` from `api-docs` plugin to allow extending it with
+custom API rendering.

plugins/api-docs/dev/asyncapi-example-api.yaml

@@ -0,0 +1,221 @@
+apiVersion: backstage.io/v1alpha1
+kind: API
+metadata:
+  name: streetlights
+  description: The Smartylighting Streetlights API allows you to remotely manage the city lights.
+  tags:
+    - mqtt
+spec:
+  type: asyncapi
+  lifecycle: production
+  owner: team-c
+  definition: |
+    asyncapi: 2.0.0
+    info:
+      title: Streetlights API
+      version: '1.0.0'
+      description: |
+        The Smartylighting Streetlights API allows you to remotely manage the city lights.
+
+        ### Check out its awesome features:
+
+        * Turn a specific streetlight on/off 🌃
+        * Dim a specific streetlight 😎
+        * Receive real-time information about environmental lighting conditions 📈
+      license:
+        name: Apache 2.0
+        url: https://www.apache.org/licenses/LICENSE-2.0
+
+    servers:
+      production:
+        url: api.streetlights.smartylighting.com:{port}
+        protocol: mqtt
+        description: Test broker
+        variables:
+          port:
+            description: Secure connection (TLS) is available through port 8883.
+            default: '1883'
+            enum:
+              - '1883'
+              - '8883'
+        security:
+          - apiKey: []
+          - supportedOauthFlows:
+            - streetlights:on
+            - streetlights:off
+            - streetlights:dim
+          - openIdConnectWellKnown: []
+
+    defaultContentType: application/json
+
+    channels:
+      smartylighting/streetlights/1/0/event/{streetlightId}/lighting/measured:
+        description: The topic on which measured values may be produced and consumed.
+        parameters:
+          streetlightId:
+            $ref: '#/components/parameters/streetlightId'
+        subscribe:
+          summary: Receive information about environmental lighting conditions of a particular streetlight.
+          operationId: receiveLightMeasurement
+          traits:
+            - $ref: '#/components/operationTraits/kafka'
+          message:
+            $ref: '#/components/messages/lightMeasured'
+
+      smartylighting/streetlights/1/0/action/{streetlightId}/turn/on:
+        parameters:
+          streetlightId:
+            $ref: '#/components/parameters/streetlightId'
+        publish:
+          operationId: turnOn
+          traits:
+            - $ref: '#/components/operationTraits/kafka'
+          message:
+            $ref: '#/components/messages/turnOnOff'
+
+      smartylighting/streetlights/1/0/action/{streetlightId}/turn/off:
+        parameters:
+          streetlightId:
+            $ref: '#/components/parameters/streetlightId'
+        publish:
+          operationId: turnOff
+          traits:
+            - $ref: '#/components/operationTraits/kafka'
+          message:
+            $ref: '#/components/messages/turnOnOff'
+
+      smartylighting/streetlights/1/0/action/{streetlightId}/dim:
+        parameters:
+          streetlightId:
+            $ref: '#/components/parameters/streetlightId'
+        publish:
+          operationId: dimLight
+          traits:
+            - $ref: '#/components/operationTraits/kafka'
+          message:
+            $ref: '#/components/messages/dimLight'
+
+    components:
+      messages:
+        lightMeasured:
+          name: lightMeasured
+          title: Light measured
+          summary: Inform about environmental lighting conditions for a particular streetlight.
+          contentType: application/json
+          traits:
+            - $ref: '#/components/messageTraits/commonHeaders'
+          payload:
+            $ref: "#/components/schemas/lightMeasuredPayload"
+        turnOnOff:
+          name: turnOnOff
+          title: Turn on/off
+          summary: Command a particular streetlight to turn the lights on or off.
+          traits:
+            - $ref: '#/components/messageTraits/commonHeaders'
+          payload:
+            $ref: "#/components/schemas/turnOnOffPayload"
+        dimLight:
+          name: dimLight
+          title: Dim light
+          summary: Command a particular streetlight to dim the lights.
+          traits:
+            - $ref: '#/components/messageTraits/commonHeaders'
+          payload:
+            $ref: "#/components/schemas/dimLightPayload"
+
+      schemas:
+        lightMeasuredPayload:
+          type: object
+          properties:
+            lumens:
+              type: integer
+              minimum: 0
+              description: Light intensity measured in lumens.
+            sentAt:
+              $ref: "#/components/schemas/sentAt"
+        turnOnOffPayload:
+          type: object
+          properties:
+            command:
+              type: string
+              enum:
+                - on
+                - off
+              description: Whether to turn on or off the light.
+            sentAt:
+              $ref: "#/components/schemas/sentAt"
+        dimLightPayload:
+          type: object
+          properties:
+            percentage:
+              type: integer
+              description: Percentage to which the light should be dimmed to.
+              minimum: 0
+              maximum: 100
+            sentAt:
+              $ref: "#/components/schemas/sentAt"
+        sentAt:
+          type: string
+          format: date-time
+          description: Date and time when the message was sent.
+
+      securitySchemes:
+        apiKey:
+          type: apiKey
+          in: user
+          description: Provide your API key as the user and leave the password empty.
+        supportedOauthFlows:
+          type: oauth2
+          description: Flows to support OAuth 2.0
+          flows:
+            implicit:
+              authorizationUrl: 'https://authserver.example/auth'
+              scopes:
+                'streetlights:on': Ability to switch lights on
+                'streetlights:off': Ability to switch lights off
+                'streetlights:dim': Ability to dim the lights
+            password:
+              tokenUrl: 'https://authserver.example/token'
+              scopes:
+                'streetlights:on': Ability to switch lights on
+                'streetlights:off': Ability to switch lights off
+                'streetlights:dim': Ability to dim the lights
+            clientCredentials:
+              tokenUrl: 'https://authserver.example/token'
+              scopes:
+                'streetlights:on': Ability to switch lights on
+                'streetlights:off': Ability to switch lights off
+                'streetlights:dim': Ability to dim the lights
+            authorizationCode:
+              authorizationUrl: 'https://authserver.example/auth'
+              tokenUrl: 'https://authserver.example/token'
+              refreshUrl: 'https://authserver.example/refresh'
+              scopes:
+                'streetlights:on': Ability to switch lights on
+                'streetlights:off': Ability to switch lights off
+                'streetlights:dim': Ability to dim the lights
+        openIdConnectWellKnown:
+          type: openIdConnect
+          openIdConnectUrl: 'https://authserver.example/.well-known'
+
+      parameters:
+        streetlightId:
+          description: The ID of the streetlight.
+          schema:
+            type: string
+
+      messageTraits:
+        commonHeaders:
+          headers:
+            type: object
+            properties:
+              my-app-header:
+                type: integer
+                minimum: 0
+                maximum: 100
+
+      operationTraits:
+        kafka:
+          bindings:
+            kafka:
+              clientId: my-app-id

plugins/api-docs/dev/index.tsx

@@ -14,11 +14,21 @@
  * limitations under the License.
  */
 
-import React from 'react';
+import { ApiEntity, Entity } from '@backstage/catalog-model';
+import { Content, Header, Page } from '@backstage/core';
 import { createDevApp } from '@backstage/dev-utils';
-import { ApiExplorerPage, apiDocsPlugin } from '../src/plugin';
-import { catalogApiRef } from '@backstage/plugin-catalog-react';
-import petstoreApiEntity from './example-api.yaml';
+import { catalogApiRef, EntityProvider } from '@backstage/plugin-catalog-react';
+import React from 'react';
+import {
+  apiDocsConfigRef,
+  ApiExplorerPage,
+  defaultDefinitionWidgets,
+  EntityApiDefinitionCard,
+} from '../src';
+import asyncapiApiEntity from './asyncapi-example-api.yaml';
+import graphqlApiEntity from './graphql-example-api.yaml';
+import openapiApiEntity from './openapi-example-api.yaml';
+import otherApiEntity from './other-example-api.yaml';
 
 createDevApp()
   .registerApi({
@@ -27,10 +37,80 @@ createDevApp()
     factory: () =>
       (({
         async getEntities() {
-          return { items: [petstoreApiEntity] };
+          return {
+            items: [
+              openapiApiEntity,
+              asyncapiApiEntity,
+              graphqlApiEntity,
+              otherApiEntity,
+            ],
+          };
         },
       } as unknown) as typeof catalogApiRef.T),
   })
-  .registerPlugin(apiDocsPlugin)
-  .addPage({ element: <ApiExplorerPage /> })
+  .registerApi({
+    api: apiDocsConfigRef,
+    deps: {},
+    factory: () => {
+      const definitionWidgets = defaultDefinitionWidgets();
+      return {
+        getApiDefinitionWidget: (apiEntity: ApiEntity) => {
+          return definitionWidgets.find(d => d.type === apiEntity.spec.type);
+        },
+      };
+    },
+  })
+  .addPage({ title: 'API Explorer', element: <ApiExplorerPage /> })
+  .addPage({
+    title: 'OpenAPI',
+    element: (
+      <Page themeId="home">
+        <Header title="OpenAPI" />
+        <Content>
+          <EntityProvider entity={(openapiApiEntity as any) as Entity}>
+            <EntityApiDefinitionCard />
+          </EntityProvider>
+        </Content>
+      </Page>
+    ),
+  })
+  .addPage({
+    title: 'AsyncAPI',
+    element: (
+      <Page themeId="home">
+        <Header title="AsyncAPI" />
+        <Content>
+          <EntityProvider entity={(asyncapiApiEntity as any) as Entity}>
+            <EntityApiDefinitionCard />
+          </EntityProvider>
+        </Content>
+      </Page>
+    ),
+  })
+  .addPage({
+    title: 'GraphQL',
+    element: (
+      <Page themeId="home">
+        <Header title="GraphQL" />
+        <Content>
+          <EntityProvider entity={(graphqlApiEntity as any) as Entity}>
+            <EntityApiDefinitionCard />
+          </EntityProvider>
+        </Content>
+      </Page>
+    ),
+  })
+  .addPage({
+    title: 'Other',
+    element: (
+      <Page themeId="home">
+        <Header title="Other" />
+        <Content>
+          <EntityProvider entity={(otherApiEntity as any) as Entity}>
+            <EntityApiDefinitionCard />
+          </EntityProvider>
+        </Content>
+      </Page>
+    ),
+  })
   .render();

plugins/api-docs/dev/other-example-api.yaml

@@ -0,0 +1,48 @@
+apiVersion: backstage.io/v1alpha1
+kind: API
+metadata:
+  name: hello-world
+  description: Hello World example for gRPC
+spec:
+  type: grpc
+  lifecycle: deprecated
+  owner: team-c
+  definition: |
+    // Copyright 2015 gRPC authors.
+    //
+    // Licensed under the Apache License, Version 2.0 (the "License");
+    // you may not use this file except in compliance with the License.
+    // You may obtain a copy of the License at
+    //
+    //     http://www.apache.org/licenses/LICENSE-2.0
+    //
+    // Unless required by applicable law or agreed to in writing, software
+    // distributed under the License is distributed on an "AS IS" BASIS,
+    // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    // See the License for the specific language governing permissions and
+    // limitations under the License.
+
+    syntax = "proto3";
+
+    option java_multiple_files = true;
+    option java_package = "io.grpc.examples.helloworld";
+    option java_outer_classname = "HelloWorldProto";
+    option objc_class_prefix = "HLW";
+
+    package helloworld;
+
+    // The greeting service definition.
+    service Greeter {
+      // Sends a greeting
+      rpc SayHello (HelloRequest) returns (HelloReply) {}
+    }
+
+    // The request message containing the user's name.
+    message HelloRequest {
+      string name = 1;
+    }
+
+    // The response message containing the greetings
+    message HelloReply {
+      string message = 1;
+    }

plugins/api-docs/src/index.ts

@@ -15,6 +15,7 @@
  */
 
 export * from './components';
+export { apiDocsConfigRef } from './config';
 export {
   apiDocsPlugin,
   apiDocsPlugin as plugin,
@@ -22,7 +23,7 @@ export {
   EntityApiDefinitionCard,
   EntityConsumedApisCard,
   EntityConsumingComponentsCard,
+  EntityHasApisCard,
   EntityProvidedApisCard,
   EntityProvidingComponentsCard,
-  EntityHasApisCard,
 } from './plugin';

yarn.lock

@@ -1978,6 +1978,7 @@
     "@backstage/catalog-client" "^0.3.8"
     "@backstage/catalog-model" "^0.7.4"
     "@backstage/core" "^0.7.3"
+    "@backstage/errors" "^0.1.1"
     "@backstage/integration" "^0.5.1"
     "@backstage/integration-react" "^0.1.1"
     "@backstage/plugin-catalog-react" "^0.1.3"
@@ -2002,6 +2003,7 @@
     "@backstage/catalog-client" "^0.3.8"
     "@backstage/catalog-model" "^0.7.4"
     "@backstage/core" "^0.7.3"
+    "@backstage/errors" "^0.1.1"
     "@backstage/integration" "^0.5.1"
     "@backstage/integration-react" "^0.1.1"
     "@backstage/plugin-catalog-react" "^0.1.3"