Day18 除了Postman我還有Swagger

14th鐵人賽

KBN

團隊imac_柬埔寨7日遊

2022-10-03 22:00:07

1287 瀏覽

分享至

嗨~大家好啊，昨天我們講完了Postman的基本使用方式，今天的話也要來說另一個好用的OpenAPI 的工具 Swagger。OpenAPI 是用於描述 API 資訊的文件，包括 API 的端點、參數、輸出入格式、說明、認證等，本質上它是一個 JSON 或 YAML 文件，而文件內的 schema 則是由 OpenAPI 定義

Swagger/OpenAPI 是什麼？

Swagger 是一間名為SmartBear Software 的公司，開發出的REST API 的工具，可以幫助設計、構建、記錄和使用REST API

如何在ASP.NET CORE 中使用Swagger?

我目前在ASP.NET CORE中有使用過Swagger的時機應該只有在Web API中用到，那我們在創一個WebAPI專案時會出現下面的圖面，這裡可以看到會到啟用OpenAPI支援，這裡就是它會自動幫我們創立好Swagger的環境，但如果沒有勾就不會有

如果沒有勾到可以自己去下載Swashbuckle.AspNetCore的第三方套件

註冊Swagger

在Program.cs加上builder.Services.AddSwaggerGen();，這就可以註冊我們的Swagger進去

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.

builder.Services.AddControllers();
// Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

有需要我們會在AddSwaggerGen裡去加特別的設定

builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo
    {
        Version = "v1",
        Title = "ToDo API",
        Description = "An ASP.NET Core Web API for managing employees",
        TermsOfService = new Uri("https://example.com/terms"),
        Contact = new OpenApiContact
        {
            Name = "Example Contact",
            Url = new Uri("https://example.com/contact")
        },
    });
});

這裡我們家的內容都會在紅色框框中

中介使用

我們在註冊完Swagger後需要加入app.UseSwagger();、app.UseSwaggerUI();
通常我們還會特別先判斷是否在開發過程，所以大致上會寫成這樣

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    // 啟用中間件以將生成的 Swagger 作為 JSON 端點提供服務
    app.UseSwagger();
    // 啟用中間件以服務 SwaggerUI（HTML、JS、CSS 等）和指定 Swagger JSON 端點
    app.UseSwaggerUI(option =>｛
        options.SwaggerEndpoint("/swagger/v1/swagger.json", "v1");
    ｝);
}

app.UseAuthorization();

app.MapControllers();

app.Run();

要是現在我們開發完了商品後，我們不可能隨面把開發環境透露在外部，所以這裡是為甚麼我們只會在開發時才會看到Swagger

Swagger也會依我們controller裡的路徑把對硬的Restful API給呈現出來

這裡我們先創一個UserController.cs後，把下方的程式放入後

using Microsoft.AspNetCore.Mvc;
namespace WepApi.Controllers
{
    [Route("api/[controller]")]
    [ApiController]
    public class UserController : ControllerBase
    {
        // GET: api/<UserController>
        [HttpGet]
        public IEnumerable<string> Get()
        {
            return new string[] { "value1", "value2" };
        }

        // GET api/<UserController>/5
        [HttpGet("{id}")]
        public string Get(int id)
        {
            return "value";
        }

        // POST api/<UserController>
        [HttpPost]
        public void Post([FromBody] string value)
        {
        }

        // PUT api/<UserController>/5
        [HttpPut("{id}")]
        public void Put(int id, [FromBody] string value)
        {
        }

        // DELETE api/<UserController>/5
        [HttpDelete("{id}")]
        public void Delete(int id)
        {
        }
    }
}

Swagger長的會像這樣

若我們今天要輸入的payload需要驗證的話，我們可以去新增User.cs的檔案，裡面我們可以方我們payload特定的attribute

using System.ComponentModel.DataAnnotations;

namespace WepApi
{
    public class User
    {
        [Required] // 必要輸入值
        [MinLength(10)] // 最小長度
        public string Name { get; set; }

        [EmailAddress] // 信箱格式
        public string Email { get; set; }

        [MaxLength(100)] // 最大長度
        public int Age { get; set; }
    }
}

System.ComponentModel.DataAnnotations 提供了許多的驗證機制讓我們使用，在 Swagger 也可以使用，除了 Require 之外我再列出我常用的Attribute

EmailAddress

MaxLength

MinLength

Range

Required

Url

再來我們再把剛剛的Post放入User後，api/User了的payload就會變成我們剛剛設定的

[HttpPost]
        public void Post([FromBody] User user)
        {
            return;
        }

執行結果如下，在 Swagger UI 最下方的 Schemas 區塊也有相同的描述

在 endpoint 可以看已看到我們剛寫好的內容

最後我們在來說說 Media type，假如我們現在要宣告回應類行為json的話，我們就要在特定的路徑加入Produces，裡面再放我們要宣告的類型

[Produces("application/json")]
        [HttpGet]
        public IEnumerable<string> Get()
        {
            return new string[] { "value1", "value2" };
        }

我在在GET api/User時宣告特定回傳json時就會這樣用