From c67cc28957ac8fa1344cbdc385c77f7d54e050e8 Mon Sep 17 00:00:00 2001
From: amlakhanpal <44179909+amlakhanpal@users.noreply.github.com>
Date: Fri, 29 Aug 2025 14:09:30 -0400
Subject: [PATCH 1/2] Update API docs in IDP

---
 .../entity_model/entity_types.md              | 34 ++++++++++++++++++-
 1 file changed, 33 insertions(+), 1 deletion(-)

diff --git a/content/en/internal_developer_portal/software_catalog/entity_model/entity_types.md b/content/en/internal_developer_portal/software_catalog/entity_model/entity_types.md
index d561f9257153e..6d2619aff8cd3 100644
--- a/content/en/internal_developer_portal/software_catalog/entity_model/entity_types.md
+++ b/content/en/internal_developer_portal/software_catalog/entity_model/entity_types.md
@@ -90,7 +90,11 @@ In Software Catalog, an API (`kind:API`) refers to a collection of endpoints tha
 
 To define components within an API, you can specify values for the `components` key in the `spec` field of the entity's v3 definition. 
 
-Example YAML for `kind:api`:
+You can also include an OpenAPI spec in your entity definition in two ways: 
+
+Inline: 
+Add the OpenAPI definition under the spec field using `type: openapi`.
+
 {{< code-block lang="yaml" filename="entity.datadog.yaml" collapsible="true" >}}
 {
  "apiVersion": "v3",
@@ -182,6 +186,34 @@ Example YAML for `kind:api`:
 }
 {{< /code-block >}}
 
+File reference: 
+
+Point to an OpenAPI file stored in GitHub using the `fileref` field.
+
+{{< code-block lang="yaml" filename="entity.datadog.yaml" collapsible="true" >}}
+{
+ "apiVersion": "v3",
+ "kind": "api",
+ "metadata": {
+   "name": "payments",
+   "displayName": "Payments",
+   "owner": "Payments Team",
+ },
+ "spec": {
+   "type": "openapi",
+   "implementedBy": [
+     "service:payment",
+     "service:payments-go"
+   ],
+   "interface": {
+     fileRef: https://github.com/openapi.yaml
+   },
+   "lifecycle": "production",
+   "tier": "Tier 0"
+ }
+}
+{{< /code-block >}}
+
 The user-defined API appears in Software Catalog as shown:
 {{< img src="/tracing/software_catalog/api-page-v3.png" alt="API page for Payments API in Software Catalog" style="width:90%;" >}}
 

From 307bdce9758e2236cc17ce95eb36191af799137c Mon Sep 17 00:00:00 2001
From: amlakhanpal <44179909+amlakhanpal@users.noreply.github.com>
Date: Fri, 29 Aug 2025 15:25:47 -0400
Subject: [PATCH 2/2] Apply suggestions from docs review

Co-authored-by: Ursula Chen <58821586+urseberry@users.noreply.github.com>
---
 .../software_catalog/entity_model/entity_types.md           | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/content/en/internal_developer_portal/software_catalog/entity_model/entity_types.md b/content/en/internal_developer_portal/software_catalog/entity_model/entity_types.md
index 6d2619aff8cd3..a05565fa3baae 100644
--- a/content/en/internal_developer_portal/software_catalog/entity_model/entity_types.md
+++ b/content/en/internal_developer_portal/software_catalog/entity_model/entity_types.md
@@ -90,9 +90,9 @@ In Software Catalog, an API (`kind:API`) refers to a collection of endpoints tha
 
 To define components within an API, you can specify values for the `components` key in the `spec` field of the entity's v3 definition. 
 
-You can also include an OpenAPI spec in your entity definition in two ways: 
+You can also include an OpenAPI spec in your entity definition in two ways: inline, or through a file reference.
 
-Inline: 
+**Inline:** 
 Add the OpenAPI definition under the spec field using `type: openapi`.
 
 {{< code-block lang="yaml" filename="entity.datadog.yaml" collapsible="true" >}}
@@ -186,7 +186,7 @@ Add the OpenAPI definition under the spec field using `type: openapi`.
 }
 {{< /code-block >}}
 
-File reference: 
+**File reference:** 
 
 Point to an OpenAPI file stored in GitHub using the `fileref` field.