ASP.NET Core: Tài liệu API web ASP.NET Core với Swagger/OpenAPI
Swagger (OpenAPI) là một đặc tả ngôn ngữ bất khả tri để mô tả các API REST. Nó cho phép cả máy tính và con người hiểu được khả năng của API REST mà không cần truy cập trực tiếp vào mã nguồn. Mục tiêu chính của nó là:
- Giảm thiểu số lượng công việc cần thiết để kết nối các dịch vụ tách rời.
- Giảm lượng thời gian cần thiết để ghi lại chính xác một dịch vụ.
Hai triển khai OpenAPI chính cho .NET là Swashbuckle và NSwag, hãy xem:
OpenAPI so với Swagger
Dự án Swagger đã được tặng cho OpenAPI Initiative vào năm 2015 và từ đó được gọi là OpenAPI. Cả hai tên được sử dụng thay thế cho nhau. Tuy nhiên, "OpenAPI" đề cập đến thông số kỹ thuật. "Swagger" đề cập đến dòng sản phẩm nguồn mở và thương mại từ SmartBear hoạt động với Đặc tả OpenAPI. Các sản phẩm nguồn mở tiếp theo, chẳng hạn như OpenAPIGenerator, cũng thuộc họ Swagger, mặc dù không được SmartBear phát hành.
Nói ngắn gọn:
- OpenAPI là một đặc điểm kỹ thuật.
- Swagger là công cụ sử dụng đặc tả OpenAPI. Ví dụ: OpenAPIGenerator và SwaggerUI.
Đặc tả OpenAPI (openapi.json)
Đặc tả OpenAPI là một tài liệu mô tả các khả năng của API của bạn. Tài liệu này dựa trên XML và các chú thích thuộc tính trong các bộ controller và model. Đây là phần cốt lõi của luồng OpenAPI và được sử dụng để điều khiển công cụ, chẳng hạn như SwaggerUI. Theo mặc định, nó được đặt tên là openapi.json. Đây là một ví dụ về đặc tả OpenAPI, được rút gọn cho ngắn gọn:
{
"openapi": "3.0.1",
"info": {
"title": "API V1",
"version": "v1"
},
"paths": {
"/api/Todo": {
"get": {
"tags": [
"Todo"
],
"operationId": "ApiTodoGet",
"responses": {
"200": {
"description": "Success",
"content": {
"text/plain": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ToDoItem"
}
}
},
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ToDoItem"
}
}
},
"text/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ToDoItem"
}
}
}
}
}
}
},
"post": {
…
}
},
"/api/Todo/{id}": {
"get": {
…
},
"put": {
…
},
"delete": {
…
}
}
},
"components": {
"schemas": {
"ToDoItem": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int32"
},
"name": {
"type": "string",
"nullable": true
},
"isCompleted": {
"type": "boolean"
}
},
"additionalProperties": false
}
}
}
}
Giao diện người dùng của Swagger
Giao diện người dùng Swagger cung cấp giao diện người dùng dựa trên web cung cấp thông tin về dịch vụ, sử dụng đặc tả OpenAPI đã tạo. Cả Swashbuckle và NSwag đều bao gồm một phiên bản giao diện người dùng Swagger được nhúng để có thể lưu trữ phiên bản này trong ứng dụng ASP.NET Core của bạn bằng lệnh gọi đăng ký middleware. Giao diện người dùng web trông như thế này:
Mỗi phương thức action public trong controller của bạn có thể được kiểm tra từ giao diện người dùng. Chọn một tên phương thức để mở rộng section. Thêm bất kỳ tham số cần thiết nào và chọn Try it out!.
Ghi chú
Phiên bản giao diện người dùng Swagger được sử dụng cho ảnh chụp màn hình là phiên bản 2. Để biết ví dụ về phiên bản 3, hãy xem ví dụ về Cửa hàng thú cưng.