ASP.NET Core OpenAPI And Swagger

2024-07-01

筆記 OpenAPI 與 Swagger 的基本要點。

OpenAPI

What is OpenAPI?

OpenAPI is a specification for building APIs. It is a set of rules that developers follow when they create an API. One of the main goals of OpenAPI is to standardize the way APIs are created, making it easier for developers to understand and use them.

What is Swagger?

Swagger is a set of tools that help developers build APIs using the OpenAPI specification. It includes a web-based interface that allows developers to interact with their APIs and see how they work. Swagger also provides tools for generating documentation and client libraries for APIs.

Install Swashbuckle.AspNetCore

We install the Swashbuckle.AspNetCore NuGet package.

  <ItemGroup>
    <PackageReference Include="Swashbuckle.AspNetCore" Version="6.6.2" />
  </ItemGroup>

Setting in Program.cs:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddEndpointsApiExplorer(); // must for minimal APIs
builder.Services.AddSwaggerGen();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

Then we can browse Swagger UI at https://localhost:7127/swagger/index.html.

OpenAPI specification

The OpenAPI specification is in https://localhost:7147/swagger/v1/swagger.json, we can validate it in the Swagger Validator website 😉

Example of swagger.json

{
  "openapi": "3.0.1",
  "info": {
    "title": "Mod07",
    "version": "1.0"
  },
  "paths": {
    "/hello": {
      "get": {
        "tags": [
          "Mod07"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/product": {
      "get": {
        "tags": [
          "Mod07"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Product"
                }
              }
            }
          }
        }
      }
    },
    "/badrequest": {
      "get": {
        "tags": [
          "Mod07"
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/todoitems": {
      "get": {
        "tags": [
          "Mod07"
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      },
      "post": {
        "tags": [
          "Mod07"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TodoItem"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/todoitems/{id}": {
      "get": {
        "tags": [
          "Mod07"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      },
      "put": {
        "tags": [
          "Mod07"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TodoItem"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      },
      "delete": {
        "tags": [
          "Mod07"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/": {
      "get": {
        "tags": [
          "Mod07"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Product": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int32"
          },
          "name": {
            "type": "string",
            "nullable": true
          },
          "price": {
            "type": "number",
            "format": "double"
          }
        },
        "additionalProperties": false
      },
      "TodoItem": {
        "required": [
          "name"
        ],
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int32"
          },
          "name": {
            "maxLength": 100,
            "minLength": 0,
            "type": "string"
          },
          "isComplete": {
            "type": "boolean"
          }
        },
        "additionalProperties": false
      }
    }
  }
}