Merge pull request #1737 from SDA-SE/feat/api-catalog

Add a Prototype for API Documentations

packages/app/package.json

@@ -5,6 +5,7 @@
   "dependencies": {
     "@backstage/cli": "^0.1.1-alpha.18",
     "@backstage/core": "^0.1.1-alpha.18",
+    "@backstage/plugin-api-docs": "^0.1.1-alpha.18",
     "@backstage/plugin-catalog": "^0.1.1-alpha.18",
     "@backstage/plugin-circleci": "^0.1.1-alpha.18",
     "@backstage/plugin-explore": "^0.1.1-alpha.18",

packages/app/src/components/Root/Root.tsx

@@ -19,6 +19,7 @@ import PropTypes from 'prop-types';
 import { Link, makeStyles } from '@material-ui/core';
 import HomeIcon from '@material-ui/icons/Home';
 import ExploreIcon from '@material-ui/icons/Explore';
+import ExtensionIcon from '@material-ui/icons/Extension';
 import BuildIcon from '@material-ui/icons/BuildRounded';
 import RuleIcon from '@material-ui/icons/AssignmentTurnedIn';
 import MapIcon from '@material-ui/icons/MyLocation';
@@ -90,6 +91,7 @@ const Root: FC<{}> = ({ children }) => (
       {/* Global nav, not org-specific */}
       <SidebarItem icon={HomeIcon} to="./" text="Home" />
       <SidebarItem icon={ExploreIcon} to="explore" text="Explore" />
+      <SidebarItem icon={ExtensionIcon} to="api-docs" text="APIs" />
       <SidebarItem icon={LibraryBooks} to="docs" text="Docs" />
       <SidebarItem icon={CreateComponentIcon} to="create" text="Create..." />
       {/* End global nav */}

packages/app/src/plugins.ts

@@ -30,3 +30,4 @@ export { plugin as Rollbar } from '@backstage/plugin-rollbar';
 export { plugin as Newrelic } from '@backstage/plugin-newrelic';
 export { plugin as TravisCI } from '@roadiehq/backstage-plugin-travis-ci';
 export { plugin as Jenkins } from '@backstage/plugin-jenkins';
+export { plugin as ApiDocs } from '@backstage/plugin-api-docs';

packages/catalog-model/examples/hello-world-api.yaml

@@ -0,0 +1,46 @@
+apiVersion: backstage.io/v1alpha1
+kind: API
+metadata:
+  name: hello-world
+  description: Hello World example for gRPC
+spec:
+  type: grpc
+  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;
+    }

packages/catalog-model/examples/petstore-api.yaml

@@ -0,0 +1,119 @@
+apiVersion: backstage.io/v1alpha1
+kind: API
+metadata:
+  name: petstore
+  description: The petstore API
+spec:
+  type: openapi
+  definition: |
+    openapi: "3.0.0"
+    info:
+      version: 1.0.0
+      title: Swagger Petstore
+      license:
+        name: MIT
+    servers:
+      - url: http://petstore.swagger.io/v1
+    paths:
+      /pets:
+        get:
+          summary: List all pets
+          operationId: listPets
+          tags:
+            - pets
+          parameters:
+            - name: limit
+              in: query
+              description: How many items to return at one time (max 100)
+              required: false
+              schema:
+                type: integer
+                format: int32
+          responses:
+            '200':
+              description: A paged array of pets
+              headers:
+                x-next:
+                  description: A link to the next page of responses
+                  schema:
+                    type: string
+              content:
+                application/json:
+                  schema:
+                    $ref: "#/components/schemas/Pets"
+            default:
+              description: unexpected error
+              content:
+                application/json:
+                  schema:
+                    $ref: "#/components/schemas/Error"
+        post:
+          summary: Create a pet
+          operationId: createPets
+          tags:
+            - pets
+          responses:
+            '201':
+              description: Null response
+            default:
+              description: unexpected error
+              content:
+                application/json:
+                  schema:
+                    $ref: "#/components/schemas/Error"
+      /pets/{petId}:
+        get:
+          summary: Info for a specific pet
+          operationId: showPetById
+          tags:
+            - pets
+          parameters:
+            - name: petId
+              in: path
+              required: true
+              description: The id of the pet to retrieve
+              schema:
+                type: string
+          responses:
+            '200':
+              description: Expected response to a valid request
+              content:
+                application/json:
+                  schema:
+                    $ref: "#/components/schemas/Pet"
+            default:
+              description: unexpected error
+              content:
+                application/json:
+                  schema:
+                    $ref: "#/components/schemas/Error"
+    components:
+      schemas:
+        Pet:
+          type: object
+          required:
+            - id
+            - name
+          properties:
+            id:
+              type: integer
+              format: int64
+            name:
+              type: string
+            tag:
+              type: string
+        Pets:
+          type: array
+          items:
+            $ref: "#/components/schemas/Pet"
+        Error:
+          type: object
+          required:
+            - code
+            - message
+          properties:
+            code:
+              type: integer
+              format: int32
+            message:
+              type: string

packages/catalog-model/examples/petstore-component.yaml

@@ -0,0 +1,13 @@
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: petstore
+  description: Petstore
+spec:
+  type: service
+  lifecycle: experimental
+  owner: pets@example.com
+  implementedApis:
+    - petstore
+    - streetlights
+    - hello-world

packages/catalog-model/examples/streetlights-api.yaml

@@ -0,0 +1,217 @@
+apiVersion: backstage.io/v1alpha1
+kind: API
+metadata:
+  name: streetlights
+  description: The Smartylighting Streetlights API allows you to remotely manage the city lights.
+spec:
+  type: asyncapi
+  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

packages/catalog-model/src/EntityPolicies.ts

@@ -23,6 +23,7 @@ import {
   SchemaValidEntityPolicy,
 } from './entity';
 import {
+  ApiEntityV1alpha1Policy,
   ComponentEntityV1alpha1Policy,
   GroupEntityV1alpha1Policy,
   LocationEntityV1alpha1Policy,
@@ -78,6 +79,7 @@ export class EntityPolicies implements EntityPolicy {
         new GroupEntityV1alpha1Policy(),
         new LocationEntityV1alpha1Policy(),
         new TemplateEntityV1alpha1Policy(),
+        new ApiEntityV1alpha1Policy(),
       ]),
     ]);
   }

packages/catalog-model/src/kinds/ApiEntityV1alpha1.test.ts

@@ -0,0 +1,126 @@
+/*
+ * Copyright 2020 Spotify AB
+ *
+ * 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.
+ */
+
+import { EntityPolicy } from '../types';
+import {
+  ApiEntityV1alpha1,
+  ApiEntityV1alpha1Policy,
+} from './ApiEntityV1alpha1';
+
+describe('ApiV1alpha1Policy', () => {
+  let entity: ApiEntityV1alpha1;
+  let policy: EntityPolicy;
+
+  beforeEach(() => {
+    entity = {
+      apiVersion: 'backstage.io/v1alpha1',
+      kind: 'API',
+      metadata: {
+        name: 'test',
+      },
+      spec: {
+        type: 'openapi',
+        definition: `
+openapi: "3.0.0"
+info:
+  version: 1.0.0
+  title: Swagger Petstore
+paths:
+  /pets:
+    get:
+      summary: List all pets
+      operationId: listPets
+      responses:
+        '200':
+          description: A paged array of pets
+          content:
+            application/json:    
+              schema:
+                $ref: "#/components/schemas/Pets"
+components:
+  schemas:
+    Pet:
+      type: object
+      required:
+        - id
+        - name
+      properties:
+        id:
+          type: integer
+          format: int64
+        name:
+          type: string
+        tag:
+          type: string
+    Pets:
+      type: array
+      items:
+        $ref: "#/components/schemas/Pet"
+`,
+      },
+    };
+    policy = new ApiEntityV1alpha1Policy();
+  });
+
+  it('happy path: accepts valid data', async () => {
+    await expect(policy.enforce(entity)).resolves.toBe(entity);
+  });
+
+  it('silently accepts v1beta1 as well', async () => {
+    (entity as any).apiVersion = 'backstage.io/v1beta1';
+    await expect(policy.enforce(entity)).resolves.toBe(entity);
+  });
+
+  it('rejects unknown apiVersion', async () => {
+    (entity as any).apiVersion = 'backstage.io/v1beta0';
+    await expect(policy.enforce(entity)).rejects.toThrow(/apiVersion/);
+  });
+
+  it('rejects unknown kind', async () => {
+    (entity as any).kind = 'Wizard';
+    await expect(policy.enforce(entity)).rejects.toThrow(/kind/);
+  });
+
+  it('rejects missing type', async () => {
+    delete (entity as any).spec.type;
+    await expect(policy.enforce(entity)).rejects.toThrow(/type/);
+  });
+
+  it('rejects wrong type', async () => {
+    (entity as any).spec.type = 7;
+    await expect(policy.enforce(entity)).rejects.toThrow(/type/);
+  });
+
+  it('rejects empty type', async () => {
+    (entity as any).spec.type = '';
+    await expect(policy.enforce(entity)).rejects.toThrow(/type/);
+  });
+
+  it('rejects missing definition', async () => {
+    delete (entity as any).spec.definition;
+    await expect(policy.enforce(entity)).rejects.toThrow(/definition/);
+  });
+
+  it('rejects wrong definition', async () => {
+    (entity as any).spec.definition = 7;
+    await expect(policy.enforce(entity)).rejects.toThrow(/definition/);
+  });
+
+  it('rejects empty definition', async () => {
+    (entity as any).spec.definition = '';
+    await expect(policy.enforce(entity)).rejects.toThrow(/definition/);
+  });
+});

packages/catalog-model/src/kinds/ApiEntityV1alpha1.ts

@@ -0,0 +1,52 @@
+/*
+ * Copyright 2020 Spotify AB
+ *
+ * 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.
+ */
+
+import * as yup from 'yup';
+import type { Entity } from '../entity/Entity';
+import type { EntityPolicy } from '../types';
+
+const API_VERSION = ['backstage.io/v1alpha1', 'backstage.io/v1beta1'] as const;
+const KIND = 'API' as const;
+
+export interface ApiEntityV1alpha1 extends Entity {
+  apiVersion: typeof API_VERSION[number];
+  kind: typeof KIND;
+  spec: {
+    type: string;
+    definition: string;
+  };
+}
+
+export class ApiEntityV1alpha1Policy implements EntityPolicy {
+  private schema: yup.Schema<any>;
+
+  constructor() {
+    this.schema = yup.object<Partial<ApiEntityV1alpha1>>({
+      apiVersion: yup.string().required().oneOf(API_VERSION),
+      kind: yup.string().required().equals([KIND]),
+      spec: yup
+        .object({
+          type: yup.string().required().min(1),
+          definition: yup.string().required().min(1),
+        })
+        .required(),
+    });
+  }
+
+  async enforce(envelope: Entity): Promise<Entity> {
+    return await this.schema.validate(envelope, { strict: true });
+  }
+}

packages/catalog-model/src/kinds/ComponentEntityV1alpha1.test.ts

@@ -35,6 +35,7 @@ describe('ComponentV1alpha1Policy', () => {
         type: 'service',
         lifecycle: 'production',
         owner: 'me',
+        implementsApis: ['api-0'],
       },
     };
     policy = new ComponentEntityV1alpha1Policy();

packages/catalog-model/src/kinds/ComponentEntityV1alpha1.ts

@@ -28,6 +28,7 @@ export interface ComponentEntityV1alpha1 extends Entity {
     type: string;
     lifecycle: string;
     owner: string;
+    implementsApis?: string[];
   };
 }
 
@@ -43,6 +44,7 @@ export class ComponentEntityV1alpha1Policy implements EntityPolicy {
           type: yup.string().required().min(1),
           lifecycle: yup.string().required().min(1),
           owner: yup.string().required().min(1),
+          implementsApis: yup.array(yup.string()).notRequired(),
         })
         .required(),
     });

packages/catalog-model/src/kinds/index.ts

@@ -34,3 +34,8 @@ export type {
   TemplateEntityV1alpha1 as TemplateEntity,
   TemplateEntityV1alpha1,
 } from './TemplateEntityV1alpha1';
+export { ApiEntityV1alpha1Policy } from './ApiEntityV1alpha1';
+export type {
+  ApiEntityV1alpha1 as ApiEntity,
+  ApiEntityV1alpha1,
+} from './ApiEntityV1alpha1';

packages/cli/config/jest.js

@@ -48,8 +48,9 @@ async function getConfig() {
 
     // Default behaviour is to not apply transforms for node_modules, but we still want
     // to apply the esm-transformer to .esm.js files, since that's what we use in backstage packages.
+    // The @kyma-project/asyncapi-react library needs to be transformed.
     transformIgnorePatterns: [
-      '/node_modules/(?!.*\\.(?:esm\\.js|bmp|gif|jpg|jpeg|png|frag|xml|svg)$)',
+      '/node_modules/(?!@kyma-project/asyncapi-react/)(?!.*\\.(?:esm\\.js|bmp|gif|jpg|jpeg|png|frag|xml|svg)$)',
     ],
   };