【ASP.NET Core學習】Web API

来源:https://www.cnblogs.com/WilsonPan/archive/2019/12/05/11945856.html
-Advertisement-
Play Games

使用VSCode + NET Core3.0在ASP.NET Core中使用Web API創建 RESTful 服務，包括創建簡單Rest API、格式化輸出、JSON Patch請求、Open API（Swagger）集成 ...


 這裡介紹在ASP.NET Core中使用Web API創建 RESTful 服務，本文使用VSCode + NET Core3.0

  1. 創建簡單Rest API
  2. 格式化輸出
  3. JSON Patch請求
  4. Open API（Swagger）集成

創建簡單Rest API

在終端輸入

dotnet new webapi -n WebAPI

1. 創建Order模型，然後初始化數據

public class OrderStore
{
    public List<Order> Orders { get; } = new List<Order>();

    public OrderStore()
    {
        var random = new Random();
        foreach (var item in Enumerable.Range(1, 10))
        {
            Orders.Add(new Order
            {
                Id = item,
                OrderNo = DateTime.Now.AddSeconds(random.Next(100, 200)).AddMilliseconds(random.Next(20, 50)).Ticks.ToString(),
                Quantity = random.Next(1, 10),
                Amount = Math.Round(((decimal)random.Next(100, 500) / random.Next(2, 6)), 2)
            });
        }
    }
}
View Code

2. 簡單REST API介面

/// <summary>
/// 訂單模塊
/// </summary>
[ApiController]
[Route("[controller]")]
[FormatFilter]
public class OrderController : ControllerBase
{

    readonly Models.OrderStore _orderStore = null;
    public OrderController(Models.OrderStore orderStore)
    {
        _orderStore = orderStore;
    }

    /// <summary>
    /// 查詢所有訂單
    /// </summary>
    [HttpGet]
    public ActionResult<List<Models.Order>> GetAll() => _orderStore.Orders;

    /// <summary>
    /// 獲取訂單    
    /// </summary>
    /// <param name="id"></param>
    /// <returns></returns>
    [HttpGet("{id:int}.{format?}")]
    public ActionResult<Models.Order> GetById(int id)
    {
        var order = _orderStore.Orders.FirstOrDefault(m => m.Id == id);

        if (order == null)
        {
            return NotFound();
        }

        return order;
    }

    /// <summary>
    /// 創建訂單
    /// </summary>
    /// <param name="order"></param>
    /// <returns>成功返回訂單Id，失敗返回-1</returns>
    [HttpPost]
    public ActionResult<int> Create(Models.Order order)
    {
        if (_orderStore.Orders.Any(m => m.OrderNo == order.OrderNo))
        {
            return -1;
        }

        order.Id = _orderStore.Orders.Max(m => m.Id) + 1;
        _orderStore.Orders.Add(order);

        return order.Id;
    }

    /// <summary>
    /// 更新訂單
    /// </summary>
    /// <returns></returns>
    [HttpPut]
    public ActionResult<bool> Update(Models.Order model)
    {
        Console.WriteLine($"OrderNo:{model.OrderNo}");
        var order = _orderStore.Orders.FirstOrDefault(m => m.OrderNo == model.OrderNo);

        if (order == null)
        {
            return NotFound();
        }

        order.Amount = model.Amount;
        order.Quantity = model.Quantity;

        return true;
    }

    /// <summary>
    /// 更新訂單指定信息
    /// </summary>
    /// <remarks>
    /// Sample request:
    /// 
    ///     PATCH  /Order/{orderNo} 
    ///     [
    ///         {
    ///             "op": "test",
    ///             "path": "/quantity",
    ///             "value": "2"
    ///         },
    ///         {
    ///             "op": "test",
    ///             "path": "/amount",
    ///             "value": "38.28"
    ///         },
    ///         {
    ///             "op": "add",
    ///             "path": "/isComplete",
    ///             "value": "true"
    ///         },
    ///     ]
    /// </remarks>
    /// <returns>返回是否成功</returns>
    /// <response code="200">提交成功</response>
    /// <response code="400">提交參數異常</response>    
    /// <response code="404">訂單號不存在</response>
    [HttpPatch("{orderNo:length(18)}")]
    [ProducesResponseType(StatusCodes.Status200OK)]
    [ProducesResponseType(StatusCodes.Status404NotFound)]
    [ProducesResponseType(StatusCodes.Status400BadRequest)]
    public ActionResult<bool> Update([FromBody] JsonPatchDocument<Models.Order> patchDoc, [FromRoute] string orderNo)
    {
        var order = _orderStore.Orders.FirstOrDefault(m => m.OrderNo == orderNo);

        if (order == null)
        {
            return NotFound();
        }

        patchDoc.ApplyTo(order, ModelState);

        if (!ModelState.IsValid)
        {
            return BadRequest(ModelState);
        }

        return Ok(true);
    }
}
View Code

3. 推薦一個VS Code插件（REST Client）測試介面，官方介紹

@baseUrl = https://localhost:5001

###
GET {{baseUrl}}/Order HTTP/1.1

### 
# @name order
POST {{baseUrl}}/Order HTTP/1.1
Accept: application/json
Content-Type: application/json

{
    "OrderNo": "637109312996909246",
    "Quantity": 2,
    "Amount": 38.28
}

### 

@orderId = {{order.response.body.*}}
GET {{baseUrl}}/Order/{{orderId}}.json HTTP/1.1

### 
GET {{baseUrl}}/Order/{{orderId}}.xml HTTP/1.1
###
GET {{baseUrl}}/Order/{{orderId}} HTTP/1.1
###

PUT {{baseUrl}}/Order HTTP/1.1
Content-Type: application/json
Accept: application/json

{
    "Id": 12,
    "OrderNo": "2019112235759329",
    "Quantity": 2,
    "Amount": 38.28
}

###

GET {{baseUrl}}/Order/11

###

PATCH  {{baseUrl}}/Order/637109312996909246 HTTP/1.1
Accept: application/json
Content-Type: application/json

[
  {
    "op": "test",
    "path": "/quantity",
    "value": "2"
  },
  {
    "op": "test",
    "path": "/amount",
    "value": "38.28"
  },
  {
    "op": "add",
    "path": "/isComplete",
    "value": "true"
  },
]




Sample request:

PATCH  /Order/{orderNo} 

[
  {
    "op": "test",
    "path": "/quantity",
    "value": "2"
  },
  {
    "op": "test",
    "path": "/amount",
    "value": "38.28"
  },
  {
    "op": "add",
    "path": "/isComplete",
    "value": "true"
  },
]
View Code

簡單介紹一下，

文件尾碼是http 或 rest

定義全局變數：@baseUrl = https://localhost:5001   ，註意鏈接不加引號

### 分割多個請求

POST/PUT 請求緊跟Head請求信息，換行加上請求內容

Ctrl + Alt + R 快捷鍵 / 點Send Request發起請求  

格式化輸出

Api介面通常會是不同客戶端調用，這樣會有可能出現需要不同響應格式，例如常用的Json，XML。 ASPNET Core 預設情況下是忽略 Accept 標頭，JSON格式返回 一、支持XML格式 1. 添加xml格式化 
services.AddControllers(options =>
    {
        options.RespectBrowserAcceptHeader = true;  //接受瀏覽器標頭
    })
    .AddXmlSerializerFormatters();                   //添加XMl格式化
}

 2. 請求是添加標頭

@orderId = {{order.response.body.*}}
GET {{baseUrl}}/Order/{{orderId}} HTTP/1.1
Accept: text/xml

 若不添加標頭，預設使用JSON格式輸出

 

二、URL格式映射

1. 添加[FormatFilter]過濾器，它會檢查路由中格式是否存在，並且使用相應的格式化程式輸出

2. 路由規則添加{format?}

[HttpGet("{id:int}.{format?}")]
public ActionResult<Models.Order> GetById(int id)
{
    var order = _orderStore.Orders.FirstOrDefault(m => m.Id == id);

    if (order == null)
    {
        return NotFound();
    }

    return order;
}
View Code

 

Url響應
GET {{baseUrl}}/Order/{{orderId}} HTTP/1.1 JSON(若配置格式化輸出）
GET {{baseUrl}}/Order/{{orderId}}.xml XML(若配置格式化輸出）
GET {{baseUrl}}/Order/{{orderId}}.json JSON(若配置格式化輸出）
  三、添加基於 Newtonsoft.Json 的 JSON 格式支持   在ASPNET Core 3.0開始，不再使用Newtonsoft.Json格式化JSON，而是使用System.Text.Json格式化，我們可以替換成Newtonsoft.Json   1. 添加包 
dotnet add package Microsoft.AspNetCore.Mvc.NewtonsoftJson

 2. 配置Newtonsoft.Json

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers()
        .AddNewtonsoftJson(options =>                   //添加基於NewtonsoftJson格式化
        {
            options.SerializerSettings.DateFormatHandling = Newtonsoft.Json.DateFormatHandling.MicrosoftDateFormat;
            options.SerializerSettings.DateFormatString = "yyyy-MM-dd HH:mm:ss";
            options.SerializerSettings.NullValueHandling = Newtonsoft.Json.NullValueHandling.Ignore;
        });
}
  JSON Patch請求

PUT 和 PATCH 方法用於更新現有資源。 它們之間的區別是，PUT 會替換整個資源，而PATCH 僅指定更改。

什麼是JSON Patch?

JSON Patch官網 裡面有一句介紹的很清楚：JSON Patch is a format for describing changes to a JSON document. （一種描述Json的變化的格式）

什麼時候需要用到JSON Patch

  1. 我們返回的JSON很大，修改可能只是某些欄位
  2. 對性能要求比較大的地方
  3. 一個大的對象，好幾個地方修改，然後統一介面修改

ASPNET Core如何處理JSON Patch 請求

1. 添加包支持

dotnet add package Microsoft.AspNetCore.JsonPatch

2. 使用 HttpPatch 屬性進行批註

3. 接受 JsonPatchDocument<T>，通常帶有 [FromBody]

4. 調用 ApplyTo 以應用更改

假設我們現在有一個完成訂單的需求

  1. 檢查金額，數量是否有變更
  2. 更新IsComplete = true

下麵附上代碼和提交的JSON

控制器代碼

[HttpPatch("{orderNo:length(18)}")]
[ProducesResponseType(StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public ActionResult<bool> Update([FromBody] JsonPatchDocument<Models.Order> patchDoc, [FromRoute] string orderNo)
{
    var order = _orderStore.Orders.FirstOrDefault(m => m.OrderNo == orderNo);

    if (order == null)
    {
        return NotFound();
    }

    patchDoc.ApplyTo(order, ModelState);

    if (!ModelState.IsValid)
    {
        return BadRequest(ModelState);
    }

    return Ok(true);
}
View Code

失敗的JSON（金額校驗不過）

PATCH  {{baseUrl}}/Order/637109312996909246 HTTP/1.1
Accept: application/json
Content-Type: application/json

[
  {
    "op": "test",
    "path": "/quantity",
    "value": "2"
  },
  {
    "op": "test",
    "path": "/amount",
    "value": "38.28"
  },
  {
    "op": "add",
    "path": "/isComplete",
    "value": "true"
  },
]
View Code

 

會在ModelState裡面列出校驗不過的信息

 成功的JSON

PATCH  {{baseUrl}}/Order/637109312996909246 HTTP/1.1
Accept: application/json
Content-Type: application/json

[
  {
    "op": "test",
    "path": "/quantity",
    "value": "2"
  },
  {
    "op": "test",
    "path": "/amount",
    "value": "36.8"
  },
  {
    "op": "add",
    "path": "/isComplete",
    "value": "true"
  },
]
View Code

 

我們用Get請求重新查一下，可以看到IsComplete成功被修改了

這裡只是簡單介紹JSON Patch使用，更多使用方法參考JSON Pan官網 和 微軟文檔

 

Open API（Swagger）集成

Api 通常需要跟客戶端，前端進行溝通，需要編寫文檔，這需要花費大量時間。

Open Api是專門解決這種問題，它為RESTful api定義了一個標準的、與語言無關的介面，利用工具生成文檔，可以做到代碼即文檔(逼著開發者完善註釋)

ASPNET Core 可以使用Swashbuckle.AspNetCore或NSwag 生成Swagger 文檔

下麵介紹如何使用Swashbuckle.AspNetCore

一、使用Swashbuckle.AspNetCore

  1. 安裝Swashbuckle.AspNetCore包

    dotnet add package Swashbuckle.AspNetCore

  2. 添加並配置 Swagger 中間件

    引用命名空間：using Microsoft.OpenApi.Models; 
    services.AddSingleton<Models.OrderStore>();
                        
services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "Web Api Doc", Version = "v1" });
});
    app.UseSwagger();
                                
app.UseSwaggerUI(c =>
{
　　c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
});

　　　　 經過上面兩步就可以使用SwaggerUI來查看文檔和測試，瀏覽器打開（http://{url}/swagger）

二、添加XML註釋

上面生成的Swagger文檔是不包含XML註釋，下麵介紹如何添加XML註釋

  1. 項目文件（*.csproj）添加以下

    <PropertyGroup>     <GenerateDocumentationFile>true</GenerateDocumentationFile>     <NoWarn>$(NoWarn);1591</NoWarn> </PropertyGroup>

     加上上面生成文檔後，未註釋的函數，屬性會發出警告，警告代碼1591，忽略警告可以添加多個，分號分割

  2. AddSwaggerGen添加下麵XML支持

    services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "Web Api Doc", Version = "v1" });

    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    c.IncludeXmlComments(xmlPath);
});

  3. 方法添加註釋

    /// <summary>
/// 更新訂單指定信息
/// </summary>
/// <remarks>
/// Sample request:
/// 
///     PATCH  /Order/{orderNo} 
///     [
///         {
///             "op": "test",
///             "path": "/quantity",
///             "value": "2"
///         },
///         {
///             "op": "test",
///             "path": "/amount",
///             "value": "38.28"
///         },
///         {
///             "op": "add",
///             "path": "/isComplete",
///             "value": "true"
///         },
///     ]
/// </remarks>
/// <returns>返回是否成功</returns>
/// <response code="200">提交成功</response>
/// <response code="400">提交參數異常</response>    
/// <response code="404">訂單號不存在</response>
    View Code

    ProducesResponseType 描述返回類型

    remarks 會生成請求說明

  4. 效果

Web Api 使用就介紹這些，如有錯漏，希望指出。

轉發請標明出處：https://www.cnblogs.com/WilsonPan/p/11945856.html

示例代碼：https://github.com/WilsonPan/AspNetCoreExamples/tree/master/WebApi


您的分享是我們最大的動力!

-Advertisement-
Play Games
更多相關文章
  • 快速查看
    1.Math.random Math.random()*10 輸出隨機變數方法，使用:"Math.random()*數量" 如:(int)(Math.random()*10); //隨機取一個10以內的整數 例如：定義一個隨機1到5(取不到5)的變數 [1,5) Math.random()*(n-m ...
  • tkinter事件鍵盤綁定
    tkinter事件鍵盤綁定 1 from tkinter import * 2 3 root=Tk() 4 5 #創建一個框架，在這個框架中響應事件 6 frame=Frame(root, 7 width=200,height=200, 8 background='green') 9 10 def ...
  • Spring 框架基礎(05)：事務管理機制，和實現方式
    本文源碼： "GitHub·點這裡" || "GitEE·點這裡" 一、Spring事務管理 1、基礎描述 事務管理的本質就是封裝了資料庫對事務支持的操作，使用JDBC的事務管理機制,就是利用 對象完成對事務的提交和回滾。 2、事務常見概念 事務 事務是指作為單個邏輯工作單元執行的一系列操作（SQL ...
  • 簡單的ssm搭建xml方式
    https://blog.csdn.net/Smile__1/article/details/103393618 ...
  • Python之數據分析工具包介紹以及安裝【入門必學】
    前言本文的文字及圖片來源於網路,僅供學習、交流使用,不具有任何商業用途,版權歸原作者所有,如有問題請及時聯繫我們以作處理。 首先我們來看 Mac版 按照需求大家依次安裝，如果你還沒學到數據分析，建議你先學好Pytho基礎和爬蟲再來。可以去小編的Python交流.裙 ：一久武其而而流一思（數字的諧音） ...
  • Nio學習筆記(大部分網上摘抄)
    Nio與IO的區別 原有的 IO 是面向流的、阻塞的，NIO 則是面向塊的、非阻塞的。 1.IO流每次從流中讀一個或多個位元組，直至讀完所有位元組，他們沒有被緩存在其他地方，並且，IO流不能移動流中的數據，如果需要前後移動從流中讀取的教據，需要先將它緩存到一個緩衝區。Java NIO的緩衝導向方法略有不 ...
  • Python對 Excel 的常用操作
    幾個常用的對象 Workbook：工作簿，一個包含多個Sheet的Excel文件 Worksheet：工作表，一個Workbook有多個Worksheet，如“Sheet1”,“Sheet2”等 Cell：單元格，存儲具體的數據對象 導入包 創建Workbook、Worksheet 寫入數據 保存 ...
  • Python小練習：StringIO和BytesIO讀寫操作的小思考
    上面這種方法“無論如何”都讀不出f的內容，使用readlines和迴圈也不行。 但是，用以下的方法，卻可以“正常讀取”： 這是為什麼呢？ PS：遇到問題沒人解答？需要Python學習資料？可以加點擊下方鏈接自行獲取 note.youdao.com/noteshare?id=2dce86d0c2588 ...
一周排行
    -Advertisement-
    Play Games
  • 移動開發（一）：使用.NET MAUI開發第一個安卓APP
    移動開發（一）：使用.NET MAUI開發第一個安卓APP 對於工作多年的C#程式員來說，近來想嘗試開發一款安卓APP，考慮了很久最終選擇使用.NET MAUI這個微軟官方的框架來嘗試體驗開發安卓APP，畢竟是使用Visual Studio開發工具，使用起來也比較的順手，結合微軟官方的教程進行了安卓 ...
  • wpf ToggleButton選中效果和一個登錄界面
    前言 QuestPDF 是一個開源 .NET 庫，用於生成 PDF 文檔。使用了C# Fluent API方式可簡化開發、減少錯誤並提高工作效率。利用它可以輕鬆生成 PDF 報告、發票、導出文件等。 項目介紹 QuestPDF 是一個革命性的開源 .NET 庫，它徹底改變了我們生成 PDF 文檔的方 ...
  • 彈幕樹洞項目功能新增篇
    項目地址 項目後端地址： https://github.com/ZyPLJ/ZYTteeHole 項目前端頁面地址： ZyPLJ/TreeHoleVue (github.com) https://github.com/ZyPLJ/TreeHoleVue 目前項目測試訪問地址： http://tree ...
  • 第27篇 sqlserver2022詳細安裝步驟
    話不多說，直接開乾 一.下載 1.官方鏈接下載： https://www.microsoft.com/zh-cn/sql-server/sql-server-downloads 2.在下載目錄中找到下麵這個小的安裝包 SQL2022-SSEI-Dev.exe，運行開始下載SQL server； 二. ...
  • .NET 開源高性能 MQTT 類庫
    前言 隨著物聯網（IoT）技術的迅猛發展，MQTT（消息隊列遙測傳輸）協議憑藉其輕量級和高效性，已成為眾多物聯網應用的首選通信標準。 MQTTnet 作為一個高性能的 .NET 開源庫，為 .NET 平臺上的 MQTT 客戶端與伺服器開發提供了強大的支持。 本文將全面介紹 MQTTnet 的核心功能 ...
  • Serilog文檔翻譯系列（六） - 可用的接收器、增強器、格式化輸出
    Serilog支持多種接收器用於日誌存儲，增強器用於添加屬性，LogContext管理動態屬性，支持多種輸出格式包括純文本、JSON及ExpressionTemplate。還提供了自定義格式化選項，適用於不同需求。 ...
  • 警惕 Visual Studio 屬性求值副作用導致邏輯不符合預期
    目錄簡介獲取 HTML 文檔解析 HTML 文檔測試參考文章 簡介 動態內容網站使用 JavaScript 腳本動態檢索和渲染數據，爬取信息時需要模擬瀏覽器行為，否則獲取到的源碼基本是空的。 本文使用的爬取步驟如下： 使用 Selenium 獲取渲染後的 HTML 文檔 使用 HtmlAgility ...
  • [使用目前最新版]HybridCLR6.9.0+YooAsset2.2.4實現純C# Unity熱更新方案 (一)
    1.前言 什麼是熱更新 游戲或者軟體更新時，無需重新下載客戶端進行安裝，而是在應用程式啟動的情況下，在內部進行資源或者代碼更新 Unity目前常用熱更新解決方案 HybridCLR，Xlua，ILRuntime等 Unity目前常用資源管理解決方案 AssetBundles，Addressable， ...
  • 在 ASP.NET Core Web API 中使用操作篩選器統一處理通用操作
    本文章主要是在C# ASP.NET Core Web API框架實現向手機發送驗證碼簡訊功能。這裡我選擇是一個互億無線簡訊驗證碼平臺，其實像阿裡雲，騰訊雲上面也可以。 首先我們先去 互億無線 https://www.ihuyi.com/api/sms.html 去註冊一個賬號 註冊完成賬號後，它會送 ...
  • 第28篇 如何.net中實現高效可靠數據同步api
    通過以下方式可以高效，並保證數據同步的可靠性 1.API設計 使用RESTful設計，確保API端點明確，並使用適當的HTTP方法（如POST用於創建，PUT用於更新）。 設計清晰的請求和響應模型，以確保客戶端能夠理解預期格式。 2.數據驗證 在伺服器端進行嚴格的數據驗證，確保接收到的數據符合預期格 ...
所有分類