.Net Core Web Api_笔记21_Swagger及OpenAPI介绍与配置使用方式_API管理与测试探讨

Swagger 是一套web api管理於测试的工具
甚至可协助提供自订API规格文件与呼叫回应方式的描述

以下是台中交通API的实际案例
https://datacenter.taichung.gov.tw/swagger/api-docs/

於2015年Swagger就捐赠给OpenAPI计画
也因此有OpenAPI的别称

不过通常习惯将OpenAPI视为一种规范而Swagger则是实践该规范的工具。
OpenAPI 注重开发者写出来的API可跟调用呼叫者很直接的合作而不用透过程序码存取

我们可从OpenAPI规范看出访问的URL与HTTP Method采用何种(GET,PUT,POST...)
跟参数与资料型别

因此用户端可以很清楚如何去呼叫使用更能让二次开发者能够无缝接轨

Swagger其实相当於一个根据OpenAPI规范发展出来一系列产品的品牌。
旗下也有诸多不同的工具比方OpenAPIGenerator , NSwag , Swashbuckle ....

Swagger UI 则是提供了Web 介面 使用OpenAPI规范提供资讯。

而我们於.NET Core开发框架则可透过middleware方式注册NSwag , Swashbuckle

Swagger 3 Web UI

Swagger 2 Web UI

.net core web api应用Swagger配置使用

在此我拿之前跑的这几篇最终产出的专案去配置

.Net Core Web Api_笔记13_api结合ADO.NET资料库操作part1_专案前置准备到资料新增

.Net Core Web Api_笔记14_api结合ADO.NET资料库操作part2_资料查询呈现

.Net Core Web Api_笔记15_api结合ADO.NET资料库操作part3_资料删除

.Net Core Web Api_笔记16_api结合ADO.NET资料库操作part4_资料编辑提交更新

.Net Core Web Api_笔记17_api结合ADO.NET资料库操作part5_新闻文章新增_新闻类别元素透过API绑定方式

.Net Core Web Api_笔记18_api结合ADO.NET资料库操作part6_新闻文章表格陈列查询

.Net Core Web Api_笔记19_api结合ADO.NET资料库操作part7_新闻文章的编辑更新与删除

.Net Core Web Api_笔记20_api结合ADO.NET资料库操作part8_新闻文章查询

到Nuget套件去下载安装NSwag.AspNetCore

紧接着我们到Starup的ConfigureServices方法去注册服务

再到Configure去启用OpenAPI跟SwaggerUI的中间件

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;

namespace MyNet5ApiAdoTest
{
    public class Startup
    {
        public Startup(IConfiguration configuration)
        {
            Configuration = configuration;
        }

        public IConfiguration Configuration { get; }

        // This method gets called by the runtime. Use this method to add services to the container.
        public void ConfigureServices(IServiceCollection services)
        {
            services.AddControllers();
            services.AddSwaggerDocument();//注册NSwag提供的服务
        }

        // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
        public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }            

            app.UseStaticFiles();
            app.UseRouting();

            app.UseAuthorization();

            app.UseOpenApi();//启用OpenAPI,预设路由/swagger/v1/swagger.json

            app.UseSwaggerUi3();//启用SwaggerUi version 3

            app.UseEndpoints(endpoints =>
            {
                endpoints.MapControllers();
            });
        }
    }
}

最後就是见证奇蹟的时刻(对於懒得写API文件的开发者来说真的是一大福音)
要查看Swagger API 自动帮我们扫描所有API 方法後产生出来的WEB API Document
预设路由/swagger
会自动跳转至/swagger/index.html

而且还真的能执行存取异动

Ref:

OpenAPI Specification
https://swagger.io/resources/open-api/

使用 Swagger/OpenAPI ASP.NET Core web API 档
https://docs.microsoft.com/zh-tw/aspnet/core/tutorials/web-api-help-pages-using-swagger?view=aspnetcore-6.0

NSwag 与 ASP.NET Core 使用者入门
https://docs.microsoft.com/zh-tw/aspnet/core/tutorials/getting-started-with-nswag?view=aspnetcore-6.0&tabs=visual-studio

Swashbuckle 与 ASP.NET Core 使用者入门
https://docs.microsoft.com/zh-tw/aspnet/core/tutorials/getting-started-with-swashbuckle?view=aspnetcore-6.0&tabs=visual-studio

本篇已同步发表至个人部落格
https://coolmandiary.blogspot.com/2021/12/net-core-web-api21swaggeropenapiapi.html