Add custom API entity page to create-app

.changeset/seven-tips-begin.md

@@ -1,6 +1,13 @@
 ---
-'@backstage/create-app': patch
-'@backstage/plugin-api-docs': patch
+'@backstage/plugin-api-docs': minor
 ---
 
-Add tables with consumes and provides relationships to the API and component entity pages.
+Stop exposing a custom router from the `api-docs` plugin. Instead, use the
+widgets exported by the plugin to compose your custom entity pages.
+
+Instead of displaying the API definitions directly in the API tab of the
+component, it now contains tables linking to the API entities. This also adds
+new widgets to display relationships (bot provides & consumes relationships)
+between components and APIs.
+
+See the changelog of `create-app` for a migration guide.

.changeset/seven-tips-more.md

@@ -6,10 +6,13 @@ Adjust template to the latest changes in the `api-docs` plugin.
 
 ## Template Changes
 
-While updating to the latest `api-docs` plugin, the following changes are necessary for the `create-app` template in your `app/src/components/catalog/EntityPage.tsx`. This adds:
+While updating to the latest `api-docs` plugin, the following changes are
+necessary for the `create-app` template in your
+`app/src/components/catalog/EntityPage.tsx`. This adds:
 
 - A custom entity page for API entities
-- Changes the API tab to include the new `ConsumedApisCard` and `ProvidedApisCard` that link to the API entity.
+- Changes the API tab to include the new `ConsumedApisCard` and
+  `ProvidedApisCard` that link to the API entity.
 
 ```diff
  import {

packages/create-app/templates/default-app/packages/app/src/components/catalog/EntityPage.tsx

@@ -13,9 +13,15 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { Entity } from '@backstage/catalog-model';
+import { ApiEntity, Entity } from '@backstage/catalog-model';
 import { WarningPanel } from '@backstage/core';
-import { ConsumedApisCard, ProvidedApisCard } from '@backstage/plugin-api-docs';
+import {
+  ApiDefinitionCard,
+  ConsumedApisCard, 
+  ConsumingComponentsCard, 
+  ProvidedApisCard, 
+  ProvidingComponentsCard
+} from '@backstage/plugin-api-docs';
 import {
   AboutCard, EntityPageLayout,
   useEntity
@@ -128,8 +134,7 @@ const DefaultEntityPage = ({ entity }: { entity: Entity }) => (
   </EntityPageLayout>
 );
 
-export const EntityPage = () => {
-  const { entity } = useEntity();
+export const ComponentEntityPage = ({ entity }: { entity: Entity }) => {
   switch (entity?.spec?.type) {
     case 'service':
       return <ServiceEntityPage entity={entity} />;
@@ -139,3 +144,55 @@ export const EntityPage = () => {
       return <DefaultEntityPage entity={entity} />;
   }
 };
+
+const ApiOverviewContent = ({ entity }: { entity: Entity }) => (
+  <Grid container spacing={3}>
+    <Grid item md={6}>
+      <AboutCard entity={entity} />
+    </Grid>
+    <Grid container item md={12}>
+      <Grid item md={6}>
+        <ProvidingComponentsCard entity={entity} />
+      </Grid>
+      <Grid item md={6}>
+        <ConsumingComponentsCard entity={entity} />
+      </Grid>
+    </Grid>
+  </Grid>
+);
+
+const ApiDefinitionContent = ({ entity }: { entity: ApiEntity }) => (
+  <Grid container spacing={3}>
+    <Grid item xs={12}>
+      <ApiDefinitionCard apiEntity={entity} />
+    </Grid>
+  </Grid>
+);
+
+const ApiEntityPage = ({ entity }: { entity: Entity }) => (
+  <EntityPageLayout>
+    <EntityPageLayout.Content
+      path="/*"
+      title="Overview"
+      element={<ApiOverviewContent entity={entity} />}
+    />
+    <EntityPageLayout.Content
+      path="/definition/*"
+      title="Definition"
+      element={<ApiDefinitionContent entity={entity as ApiEntity} />}
+    />
+  </EntityPageLayout>
+);
+
+export const EntityPage = () => {
+  const { entity } = useEntity();
+
+  switch (entity?.kind?.toLowerCase()) {
+    case 'component':
+      return <ComponentEntityPage entity={entity} />;
+    case 'api':
+      return <ApiEntityPage entity={entity} />;
+    default:
+      return <DefaultEntityPage entity={entity} />;
+  }
+};