Modify an OpenAPI document

  • Article

The PetStore API described in Create an OpenAPI document has only one path for getting all pets. Imagine the API adds the capability to add a pet to the store.

This example adds a new path to the OpenAPI document to describe a new endpoint for adding a pet to the store.

using Microsoft.OpenApi.Models;
using Microsoft.OpenApi.Readers;
using Microsoft.OpenApi.Writers;

// Load the existing OpenAPI document from a YAML file
using var streamReader = new StreamReader("pet-store.yaml");
var reader = new OpenApiStreamReader();
var document = reader.Read(streamReader.BaseStream, out var diagnostic);

// Add a new property to the Pet schema
var categoryProperty = new OpenApiSchema
{
    Type = "object",
    Properties = new Dictionary<string, OpenApiSchema>
    {
        ["id"] = new OpenApiSchema
        {
            Type = "integer",
        },
        ["name"] = new OpenApiSchema
        {
            Type = "string",
        },
    },
};

document.Components.Schemas["Pet"].Properties.Add("category", categoryProperty);

// Add a new path
var newPetPath = new OpenApiPathItem
{
    Operations = new Dictionary<OperationType, OpenApiOperation>
    {
        [OperationType.Post] = new OpenApiOperation
        {
            Description = "Add a new pet",
            RequestBody = new OpenApiRequestBody
            {
                Content = new Dictionary<string, OpenApiMediaType>
                {
                    ["application/json"] = new OpenApiMediaType
                    {
                        Schema = new OpenApiSchema
                        {
                            Reference = new OpenApiReference
                            {
                                Type = ReferenceType.Schema,
                                Id = "Pet",
                            },
                        },
                    },
                },
                Required = true, // Indicates that the body is required
            },
            Responses = new OpenApiResponses
            {
                ["201"] = new OpenApiResponse
                {
                    Description = "Pet created successfully",
                },
            },
        },
    },
};

// Add the new path to the document
document.Paths.Add("/pets/post", newPetPath);

// Serialize and save the modified OpenAPI document to a new file
using var streamWriter = new StreamWriter("updated-pet-store.yaml");
var writer = new OpenApiYamlWriter(streamWriter);
document.SerializeAsV3(writer);
Console.WriteLine("PetStore OpenAPI document updated.");

The following YAML snippet is how the modified OpenAPI description for PetStore service looks now:

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

Next steps