Merge pull request #98 from MicrosoftDocs/main

Merge main to live

.github/workflows/markdown.yml

@@ -5,6 +5,9 @@ on:
     branches: [ main, live ]
   push:
     branches: [ main, live ]
+permissions:
+  pull-requests: read
+  contents: read
 
 jobs:
   lint:

OpenAPI/OpenAPI.NET/overview.md

@@ -0,0 +1,33 @@
+---
+title: Overview
+description: Learn about the features and use cases for the OpenAPI.NET library
+author: njaci1
+ms.author: kelvinnjaci
+ms.topic: conceptual
+---
+
+# OpenAPI.NET library
+
+OpenAPI.NET is a .NET library for working with OpenAPI documents. OpenAPI is a standard specification for describing HTTP APIs in a machine-readable and human-friendly way. With OpenAPI.NET, you can create, modify, validate, and convert (between JSON and YAML) OpenAPI documents in your .NET applications. The library includes readers and writers for serializing and deserializing OpenAPI documents to and from different formats and versions.
+
+At a high level, OpenAPI.NET works by providing an object model for OpenAPI documents. This object model represents the different components of an OpenAPI document, such as its paths, operations, parameters, and responses.
+
+## Benefits of using OpenAPI.NET
+
+Some of the benefits of using the OpenAPI.NET library when working with OpenAPI documents include:
+
+- **Ease of use:** OpenAPI.NET provides a useful object model for OpenAPI documents, making it easy to create and manipulate OpenAPI documents in your .NET code.
+
+- **Flexibility:** OpenAPI.NET includes readers and writers for serializing and deserializing OpenAPI documents to and from different formats, including JSON and YAML, giving you the flexibility to work with OpenAPI documents in the format of your choice.
+
+- **Reliability:** OpenAPI.NET can validate OpenAPI documents to ensure that they conform to the OpenAPI specification, helping you to catch and fix errors early in the development process.
+
+- **Interoperability:** OpenAPI.NET can convert OpenAPI documents between different versions (versions 2.0 and 3.0 and soon 3.1) of the OpenAPI specification, as well as between different formats (JSON and YAML), making it easy to share and collaborate on OpenAPI documents with others.
+
+- **Customization:** OpenAPI.NET supports changing the validation rules and creating custom serializers/deserializer for extensions.
+
+## See also
+
+- [Creating an OpenAPI document](create-openapi.md)
+- [Modifying an OpenAPI document](modify-openapi.md)
+- [Converting an OpenAPI document](convert-openapi.md)

OpenAPI/index.yml

@@ -87,9 +87,12 @@ tools:
   title: OpenAPI Tools
   summary: Tooling and SDKs for working with OpenAPI
   items:
-  - title: OpenAPI.NET (Microsoft.OpenApi)
-    imageSrc: /media/common/i_tools.svg
+  - title: OpenAPI.NET documentation
+    imageSrc: /media/common/i_overview.svg
+    url: ./openapi.net/overview.md
+  - title: OpenAPI.NET (Microsoft.OpenApi) reference
+    imageSrc: /media/common/i_reference.svg
     url: /dotnet/api/microsoft.openapi
-  - title: Microsoft.OpenApi.OData
-    imageSrc: /media/common/i_code-blocks.svg
+  - title: Microsoft.OpenApi.OData reference
+    imageSrc: /media/common/i_reference.svg
     url: /dotnet/api/microsoft.openapi.odata

OpenAPI/openapi.net/convert-openapi.md

@@ -0,0 +1,166 @@
+---
+title: Convert an OpenAPI document
+description: Learn how to use the OpenAPI.NET library to convert OpenAPI documents between YAML and JSON
+author: njaci1
+ms.author: kelvinnjaci
+ms.topic: conceptual
+---
+
+# Convert an OpenAPI document
+
+OpenAPI.NET has the ability to convert OpenAPI documents between different formats, such as YAML or JSON. This can be useful when you need to share or collaborate on an OpenAPI document with others who may prefer a different format.
+
+Here is an example of how you can convert an OpenAPI document from YAML to JSON using OpenAPI.NET.
+
+This example converts the OpenAPI document [created](create-openapi.md) and [modified](modify-openapi.md) in the previous examples from YAML to JSON.
+
+```csharp
+using Microsoft.OpenApi.Readers;
+using Microsoft.OpenApi.Writers;
+
+// Load the existing OpenAPI document from a YAML file
+using var streamReader = new StreamReader("updated-pet-store.yaml");
+var reader = new OpenApiStreamReader();
+var document = reader.Read(streamReader.BaseStream, out var diagnostic);
+
+// Serialize and save the OpenAPI document to a JSON file
+using var streamWriter = new StreamWriter("updated-pet-store.json");
+var writer = new OpenApiJsonWriter(streamWriter);
+document.SerializeAsV3(writer);
+
+Console.WriteLine("OpenAPI document converted from YAML to JSON.");
+```
+
+Compare the original YAML with the new JSON.
+
+## YAML
+
+```yaml
+openapi: 3.0.1
+info:
+  title: PetStore API
+  version: 1.0.0
+servers:
+  - url: https://api.petstore.com
+paths:
+  /pets:
+    get:
+      description: Get all pets
+      responses:
+        '200':
+          description: A list of pets
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Pet'
+  /pets/post:
+    post:
+      description: Add a new pet
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Pet'
+        required: true
+      responses:
+        '201':
+          description: Pet created successfully
+components:
+  schemas:
+    Pet:
+      type: object
+      properties:
+        name:
+          type: string
+        category:
+          type: object
+          properties:
+            id:
+              type: integer
+            name:
+              type: string
+```
+
+## JSON
+
+```json
+{
+  "openapi": "3.0.1",
+  "info": {
+    "title": "PetStore API",
+    "version": "1.0.0"
+  },
+  "servers": [
+    {
+      "url": "https://api.petstore.com"
+    }
+  ],
+  "paths": {
+    "/pets": {
+      "get": {
+        "description": "Get all pets",
+        "responses": {
+          "200": {
+            "description": "A list of pets",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "array",
+                  "items": {
+                    "$ref": "#/components/schemas/Pet"
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/pets/post": {
+      "post": {
+        "description": "Add a new pet",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/Pet"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "201": {
+            "description": "Pet created successfully"
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "Pet": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string"
+          },
+          "category": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "integer"
+              },
+              "name": {
+                "type": "string"
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```

OpenAPI/openapi.net/create-openapi.md

@@ -0,0 +1,129 @@
+---
+title: Create an OpenAPI document
+description: Learn how to use the OpenAPI.NET library to create an OpenAPI document
+author: njaci1
+ms.author: kelvinnjaci
+ms.topic: conceptual
+---
+
+# Create an OpenAPI document
+
+The `OpenApiDocument` class contains methods and properties that developers use to create an OpenAPI document in code.
+
+This example defines a simple PetStore API definition that allows users to view pets in an online store. It adds a GET operation for a single path (`/pets`), and defines the `Pet` type returned by the API.
+
+```csharp
+using Microsoft.OpenApi.Models;
+using Microsoft.OpenApi.Writers;
+
+// Create an OpenAPI document for the PetStore API
+var document = new OpenApiDocument
+{
+    Info = new OpenApiInfo
+    {
+        Title = "PetStore API",
+        Version = "1.0.0",
+    },
+    Servers =
+    [
+        new OpenApiServer { Url = "https://api.petstore.com" },
+    ],
+    Paths = new OpenApiPaths
+    {
+        ["/pets"] = new OpenApiPathItem
+        {
+            Operations = new Dictionary<OperationType, OpenApiOperation>
+            {
+                [OperationType.Get] = new OpenApiOperation
+                {
+                    Description = "Get all pets",
+                    Responses = new OpenApiResponses
+                    {
+                        ["200"] = new OpenApiResponse
+                        {
+                            Description = "A list of pets",
+                            Content = new Dictionary<string, OpenApiMediaType>
+                            {
+                                ["application/json"] = new OpenApiMediaType
+                                {
+                                    Schema = new OpenApiSchema
+                                    {
+                                        Type = "array",
+                                        Items = new OpenApiSchema
+                                        {
+                                            Reference = new OpenApiReference
+                                            {
+                                                Type = ReferenceType.Schema,
+                                                Id = "Pet",
+                                            },
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                },
+            },
+        },
+    },
+    Components = new OpenApiComponents
+    {
+        Schemas = new Dictionary<string, OpenApiSchema>
+        {
+            ["Pet"] = new OpenApiSchema
+            {
+                Type = "object",
+                Properties = new Dictionary<string, OpenApiSchema>
+                {
+                    ["name"] = new OpenApiSchema
+                    {
+                        Type = "string",
+                    },
+                },
+            },
+        },
+    },
+};
+
+// Serialize the OpenAPI document to a YAML file
+using var streamWriter = new StreamWriter("pet-store.yaml");
+var writer = new OpenApiYamlWriter(streamWriter);
+document.SerializeAsV3(writer);
+Console.WriteLine("PetStore OpenAPI document created and saved.");
+```
+
+Here is the resulting OpenAPI description for our PetStore service:
+
+```yaml
+openapi: 3.0.1
+info:
+  title: PetStore API
+  version: 1.0.0
+servers:
+  - url: https://api.petstore.com
+paths:
+  /pets:
+    get:
+      description: Get all pets
+      responses:
+        '200':
+          description: A list of pets
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Pet'
+components:
+  schemas:
+    Pet:
+      type: object
+      properties:
+        name:
+          type: string
+```
+
+## Next steps
+
+- See [Modifying an OpenAPI document](modify-openapi.md) to learn how to add a new path to this OpenAPI document.
+- See [Converting an OpenAPI document](convert-openapi.md) to learn how to use the OpenAPI.NET library to convert between YAML and JSON formats.