หน้าแรก>การเขียนโปรแกรมที่เกี่ยวข้อง>ซอร์สโค้ดอื่น ๆ
ดาวน์โหลด
แจ้งให้ทราบสำคัญหากคุณอัพเกรดระหว่างเวอร์ชันหลัก!
* หากคุณอัพเกรดจาก 4.x เป็น 5.x มีการเปลี่ยนแปลงหลายอย่างที่ต้องระวัง ดูบันทึกประจำรุ่นสำหรับรายละเอียด
* หากคุณกำลังกระโดดจาก 3.x เป็น 4.x ก่อนจะมีมังกรอยู่ที่นั่นด้วย ดูบันทึกย่อเหล่านั้นที่นี่

swashbuckle.aspnetcore

Swagger Tooling สำหรับ APIs ที่สร้างด้วย ASP.NET Core สร้างเอกสาร API ที่สวยงามรวมถึง UI เพื่อสำรวจและทดสอบการดำเนินการโดยตรงจากเส้นทางคอนโทรลเลอร์และรุ่นของคุณ

นอกเหนือจากเครื่องกำเนิดไฟฟ้า Swagger 2.0 และ Openapi 3.0 แล้ว Swashbuckle ยังให้บริการรุ่นที่น่ากลัวของ Swagger-Ui ที่ขับเคลื่อนโดย Json Swagger ที่สร้างขึ้น ซึ่งหมายความว่าคุณสามารถเติมเต็ม API ของคุณด้วยเอกสารประกอบการใช้ชีวิตที่ซิงค์กับรหัสล่าสุดเสมอ ที่ดีที่สุดคือต้องใช้การเข้ารหัสและการบำรุงรักษาน้อยที่สุดทำให้คุณสามารถมุ่งเน้นไปที่การสร้าง API ที่ยอดเยี่ยม

และนั่นไม่ใช่ทั้งหมด ...

เมื่อคุณมี API ที่สามารถอธิบายตัวเองได้ใน Swagger คุณได้เปิดหีบสมบัติของเครื่องมือที่ใช้ Swagger รวมถึงเครื่องกำเนิดลูกค้าที่สามารถกำหนดเป้าหมายไปยังแพลตฟอร์มยอดนิยมที่หลากหลาย ดู Swagger-Codegen สำหรับรายละเอียดเพิ่มเติม

ความเข้ากันได้

รุ่น Swashbuckle ASP.NET CORE swagger / openapi spec Swagger-ui redoc ui
CI > = 2.0.0 2.0, 3.0 5.xx 2.xx
6.9.0 > = 2.0.0 2.0, 3.0 5.17.14 2.1.5
5.6.3 > = 2.0.0 2.0, 3.0 3.32.5 2.0.0-rc.40
4.0.0 > = 2.0.0, <3.0.0 2.0 3.19.5 1.22.2
3.0.0 > = 1.0.4, <3.0.0 2.0 3.17.1 1.20.0
2.5.0 > = 1.0.4, <3.0.0 2.0 3.16.0 1.20.0

เริ่มต้น

  1. ติดตั้งแพ็คเกจ NUGET มาตรฐานลงในแอปพลิเคชัน ASP.NET Core ของคุณ 

    Package Manager : Install-Package Swashbuckle.AspNetCore
CLI : dotnet add package Swashbuckle.AspNetCore

  2. ในวิธี ConfigureServices ของ Startup.cs ลงทะเบียนเครื่องกำเนิด Swagger กำหนดเอกสาร Swagger หนึ่งฉบับขึ้นไป

     การใช้ microsoft.openapi.models;
     services.addmvc (); services.addswaggergen (c => {c.swaggerdoc ("v1", ใหม่ openapiinfo {title = "my api", เวอร์ชัน = "v1"});});

  3. ตรวจสอบให้แน่ใจว่าการกระทำและพารามิเตอร์ของ API ของคุณได้รับการตกแต่งด้วย "HTTP" และ "จาก" การผูกที่ชัดเจน

     [httppost] โมฆะสาธารณะ createproduct ([[frombody] ผลิตภัณฑ์ผลิตภัณฑ์) ...
     [httpget] public ienumerable <product> searchproducts ([fromQuery] คำหลักสตริง) ...

    หมายเหตุ: หากคุณละเว้นการผูกพารามิเตอร์ที่ชัดเจนเครื่องกำเนิดจะอธิบายว่าเป็นพารามิเตอร์ "สอบถาม" โดยค่าเริ่มต้น

  4. ในวิธี Configure คุณควรเปิดเผย swagger ที่สร้างขึ้นเป็นจุดสิ้นสุด JSON โดยวิธีหนึ่งต่อไปนี้:

     App.MapEndpoints (endpoints => {// ... endpoints.mapswagger ();});
     app.useswagger ();

    ณ จุดนี้คุณสามารถหมุนแอปพลิเคชันของคุณและดู Swagger Json ที่สร้างขึ้นได้ที่ "/swagger/v1/swagger.json"

    • แทรกมิดเดิลแวร์

    • เพิ่มจุดสิ้นสุดหากคุณใช้การกำหนดเส้นทางตามจุดปลาย

  5. เป็นทางเลือกให้ใส่มิดเดิลแวร์ Swagger-UI หากคุณต้องการเปิดเผยเอกสารประกอบแบบโต้ตอบโดยระบุจุดสิ้นสุดของ JSON Swagger เพื่อให้พลังงานจาก

     app.useswaggerui (c => {c.swaggerendpoint ("v1/swagger.json", "my api v1");});

    ตอนนี้คุณสามารถรีสตาร์ทแอปพลิเคชันของคุณและตรวจสอบเอกสารโต้ตอบแบบโต้ตอบอัตโนมัติที่ "/Swagger"

System.Text.json (STJ) เทียบกับ Newtonsoft

ในรุ่นก่อน 5.0.0 Swashbuckle จะสร้างสคีมา (คำอธิบายของประเภทข้อมูลที่เปิดเผยโดย API) ตามพฤติกรรมของ Newtonsoft Serializer สิ่งนี้สมเหตุสมผลเพราะนั่นคือ serializer ที่ส่งมอบ ASP.NET Core ในเวลานั้น อย่างไรก็ตามเนื่องจากเวอร์ชัน 3.0.0 , ASP.NET CORE แนะนำ Serializer System.Text.json (STJ) ใหม่นอกกรอบและหากคุณต้องการใช้ Newtonsoft ต่อไปคุณต้องติดตั้งแพ็คเกจแยกต่างหาก เลือกเข้าร่วม จาก Swashbuckle 5.0.0 และเกินกว่ารูปแบบที่คล้ายกัน นั่นคือ swashbuckle นอกกรอบจะถือว่าคุณใช้ STJ serializer และสร้างสคีมาตามพฤติกรรมของมัน หากคุณใช้ Newtonsoft คุณจะต้องติดตั้งแพ็คเกจ Swashbuckle แยกต่างหากและเลือกใช้อย่างชัดเจน นี่เป็นขั้นตอนที่จำเป็นโดยไม่คำนึงถึง ASP.NET Core ที่คุณใช้อยู่

โดยสรุป ...

หากคุณใช้ System.Text.json (STJ) การตั้งค่าที่อธิบายไว้ข้างต้นจะเพียงพอและตัวเลือก/แอตทริบิวต์ STJ จะได้รับการยกย่องโดยอัตโนมัติโดยเครื่องกำเนิด Swagger

หากคุณใช้ Newtonsoft คุณจะต้องติดตั้งแพ็คเกจแยกต่างหากและเลือกใช้อย่างชัดเจนเพื่อให้แน่ใจว่าการตั้งค่า/แอตทริบิวต์ ของ Newtonsoft จะได้รับเกียรติจากเครื่องกำเนิด Swagger โดยอัตโนมัติ: 

Package Manager : Install-Package Swashbuckle.AspNetCore.Newtonsoft
CLI : dotnet add package Swashbuckle.AspNetCore.Newtonsoft
 services.addmvc (); services.addswaggergen (c => {c.swaggerdoc ("v1", ใหม่ openapiinfo {title = "my api", เวอร์ชัน = "v1"});}); services.addswaggergennewtonsoftsupport (); // การเลือกเข้าร่วมอย่างชัดเจน - จำเป็นต้องวางหลังจาก addswaggergen ()

swashbuckle, apiexplorer และการกำหนดเส้นทาง

Swashbuckle อาศัย ApiExplorer เป็นอย่างมากชั้นเมตาดาต้า API ที่จัดส่งด้วย ASP.NET Core หากคุณใช้ AddMvc Helper เพื่อ bootstrap สแต็ก MVC ดังนั้น ApiexPlorer จะลงทะเบียนโดยอัตโนมัติและ SB จะทำงานโดยไม่มีปัญหา อย่างไรก็ตามหากคุณใช้ AddMvcCore สำหรับสแต็ก MVC ที่จับคู่มากขึ้นคุณจะต้องเพิ่มบริการ ApiexPlorer อย่างชัดเจน:

 services.addmvccore (). addapiexplorer ();

นอกจากนี้หากคุณใช้ การกำหนดเส้นทางทั่วไป (ตรงข้ามกับการกำหนดเส้นทางแอตทริบิวต์) ตัวควบคุมและการกระทำของตัวควบคุมที่ใช้การกำหนดเส้นทางทั่วไปจะไม่ถูกแสดงใน Apiexplorer ซึ่งหมายความว่า Swashbuckle จะไม่สามารถหาตัวควบคุมเหล่านั้นและสร้าง Swagger การดำเนินงานจากพวกเขา ตัวอย่างเช่น:

 app.usemvc (เส้นทาง => {// swaggergen จะไม่พบคอนโทรลเลอร์ที่ถูกกำหนดเส้นทางผ่านเทคนิคนี้ Route.MapRoute ("เริ่มต้น", "{controller = home}/{action =}/{id?}") ;});

คุณ ต้อง ใช้การกำหนดเส้นทางแอตทริบิวต์สำหรับตัวควบคุมใด ๆ ที่คุณต้องการแสดงในเอกสาร Swagger ของคุณ:

 [เส้นทาง ("ตัวอย่าง")] Public Class ExampleController: คอนโทรลเลอร์ {[httpget ("")] สาธารณะ iActionResult Dostuff () { / ** /}}}

อ้างถึงเอกสารการกำหนดเส้นทางสำหรับข้อมูลเพิ่มเติม

ส่วนประกอบ

Swashbuckle ประกอบด้วยส่วนประกอบหลายอย่างที่สามารถใช้ร่วมกันหรือเป็นรายบุคคลขึ้นอยู่กับความต้องการของคุณ ที่สำคัญของมันมีเครื่องกำเนิดไฟฟ้าที่ผอมแห้งมิดเดิลแวร์ที่จะเปิดเผยเป็นจุดสิ้นสุดของ JSON และรุ่นแพคเกจของ Swagger-Ui แพ็คเกจทั้ง 3 นี้สามารถติดตั้งได้ด้วย Swashbuckle.AspNetCore "metapackage" และจะทำงานร่วมกันได้อย่างราบรื่น (ดูการเริ่มต้นใช้งาน) เพื่อให้เอกสาร API ที่สวยงามซึ่งสร้างขึ้นจากรหัสของคุณโดยอัตโนมัติ

นอกจากนี้ยังมีแพ็คเกจเสริม (เครื่องมือ CLI, UI สำรอง ฯลฯ ) ที่คุณสามารถเลือกติดตั้งและกำหนดค่าตามต้องการ

แพ็คเกจ "core" (เช่นติดตั้งผ่าน swashbuckle.aspnetcore)

บรรจุุภัณฑ์ คำอธิบาย
swashbuckle.aspnetcore.swagger เปิดเผยจุดสิ้นสุดของ JSON Swagger คาดว่าจะมีการใช้งานของ ISwaggerProvider ที่จะลงทะเบียนในคอนเทนเนอร์ DI ซึ่งจะทำการค้นหาเพื่อดึง OpenAPIDocument(s) ซึ่งถูกเปิดเผยว่าเป็น JSON อนุกรม
swashbuckle.aspnetcore.swaggergen ฉีดการใช้ ISwaggerProvider ที่สามารถใช้งานได้โดยส่วนประกอบข้างต้น การใช้งานนี้โดยเฉพาะจะสร้าง OpenApiDocument(s) จากเส้นทางคอนโทรลเลอร์และรุ่นของคุณ
swashbuckle.aspnetcore.swaggerui เปิดเผยรุ่นที่ฝังตัวของ Swagger-ui คุณระบุจุดสิ้นสุดของ API ที่สามารถรับ Swagger JSON และใช้มันเพื่อใช้จ่ายเอกสารแบบอินเทอร์แอคทีฟสำหรับ API ของคุณ

แพ็คเกจเพิ่มเติม

บรรจุุภัณฑ์ คำอธิบาย
swashbuckle.aspnetcore.annotations รวมชุดของแอตทริบิวต์ที่กำหนดเองที่สามารถนำไปใช้กับคอนโทรลเลอร์การกระทำและโมเดลเพื่อเสริมสร้างความผยองที่สร้างขึ้น
swashbuckle.aspnetcore.cli จัดเตรียมอินเทอร์เฟซบรรทัดคำสั่งสำหรับการดึง swagger โดยตรงจากชุดประกอบเริ่มต้นและเขียนไปยังไฟล์
swashbuckle.aspnetcore.redoc เปิดตัว redoc ui รุ่นที่ฝังตัว (ทางเลือกแทน Swagger-ui)

แพ็คเกจชุมชน

แพ็คเกจเหล่านี้จัดทำโดยชุมชนโอเพ่นซอร์ส

บรรจุุภัณฑ์ คำอธิบาย
swashbuckle.aspnetcore.filters ตัวกรอง swashbuckle ที่มีประโยชน์บางอย่างซึ่งเพิ่มเอกสารเพิ่มเติมเช่นคำขอและตัวอย่างการตอบกลับข้อมูลการอนุญาต ฯลฯ ดู ReadMe สำหรับรายละเอียดเพิ่มเติม
unchase.swashbuckle.aspnetcore.extensions ส่วนขยายที่มีประโยชน์บางอย่าง (ตัวกรอง) ซึ่งเพิ่มเอกสารเพิ่มเติมเช่นซ่อน partitems สำหรับบทบาทที่ไม่ได้รับการยอมรับแก้ไข enums สำหรับการสร้างรหัสลูกค้า ฯลฯ ดู ReadMe สำหรับรายละเอียดเพิ่มเติม
microelements.swashbuckle.fluentvalidation ใช้กฎการ validation fluentvalidation แทนแอตทริบิวต์ ComponentModel เพื่อเพิ่ม schemas swagger ที่สร้างขึ้น
mmlib.swaggerocelot เอกสารรวมผ่าน Microservices โดยตรงบน Ocelot API Gateway

การกำหนดค่าและการปรับแต่ง

ขั้นตอนที่อธิบายไว้ข้างต้นจะช่วยให้คุณได้รับการตั้งค่าน้อยที่สุด อย่างไรก็ตาม Swashbuckle มีความยืดหยุ่นในการปรับแต่งอย่างมากตามที่คุณเห็น ตรวจสอบตารางด้านล่างสำหรับรายการตัวเลือกทั้งหมด:

  • swashbuckle.aspnetcore.swagger

    • เปลี่ยนเส้นทางสำหรับจุดสิ้นสุดของ Swagger JSON

    • ปรับเปลี่ยน Swagger ด้วยบริบทคำขอ

    • Serialize Swagger Json ในรูปแบบ 2.0

    • การทำงานกับไดเรกทอรีเสมือนจริงและพร็อกซีย้อนกลับ

    • ปรับแต่งวิธีการจัดทำเอกสาร OpenAPI

  • swashbuckle.aspnetcore.swaggergen

    • กำหนด OperationIds ที่ชัดเจน

    • รายการตอบสนองการดำเนินงาน

    • พารามิเตอร์ที่ต้องการและคุณสมบัติสคีมา

    • จัดการแบบฟอร์มและการอัปโหลดไฟล์

    • จัดการดาวน์โหลดไฟล์

    • รวมคำอธิบายจากความคิดเห็น XML

    • ให้ข้อมูลเมตา Global API

    • สร้างเอกสาร Swagger หลายฉบับ

    • ละเว้นการดำเนินงานที่ล้าสมัยและ/หรือคุณสมบัติสคีมา

    • ละเว้นการดำเนินงานโดยพลการ

    • ปรับแต่งแท็กการทำงาน (เช่นสำหรับการจัดกลุ่ม UI)

    • เปลี่ยนลำดับการดำเนินการเรียงลำดับ (เช่นสำหรับการเรียงลำดับ UI)

    • ปรับแต่ง Schema ID

    • แทนที่สคีมาสำหรับประเภทเฉพาะ

    • ขยายเครื่องกำเนิดไฟฟ้าด้วยการทำงานตัวกรอง schema & document

    • เพิ่มคำจำกัดความและข้อกำหนดด้านความปลอดภัย

    • เพิ่มคำจำกัดความและข้อกำหนดด้านความปลอดภัยสำหรับผู้ถือ Auth

    • มรดกและความหลากหลาย

  • swashbuckle.aspnetcore.swaggerui

    • เปลี่ยนเส้นทางสัมพัทธ์เป็น UI

    • เปลี่ยนชื่อเอกสาร

    • เปลี่ยนเส้นทาง CSS หรือ JS

    • แสดงรายการเอกสาร Swagger หลายฉบับ

    • ใช้พารามิเตอร์ Swagger-UI

    • ฉีดจาวาสคริปต์ที่กำหนดเอง

    • ฉีด CSS ที่กำหนดเอง

    • ปรับแต่ง index.html

    • เปิดใช้งาน OAUTH2.0 FLOWS

    • ใช้คำขอฝั่งไคลเอ็นต์และตัวดักตอบตอบกลับ

  • swashbuckle.aspnetcore.annotations

    • ติดตั้งและเปิดใช้งานคำอธิบายประกอบ

    • Metadata Operation Operation

    • metadata การตอบสนองที่ดีขึ้น

    • เมตาดาต้าพารามิเตอร์เสริม

    • Enrich Requestbody Metadata

    • Metadata Schema

    • ใช้ตัวกรองสคีมากับประเภทเฉพาะ

    • เพิ่ม Metadata แท็ก

  • swashbuckle.aspnetcore.cli

    • ดึง swagger โดยตรงจากชุดประกอบเริ่มต้น

    • ใช้เครื่องมือ CLI ด้วยการกำหนดค่าโฮสต์ที่กำหนดเอง

  • swashbuckle.aspnetcore.redoc

    • เปลี่ยนเส้นทางสัมพัทธ์เป็น UI

    • เปลี่ยนชื่อเอกสาร

    • ใช้พารามิเตอร์ redoc

    • ฉีด CSS ที่กำหนดเอง

    • ปรับแต่ง index.html

swashbuckle.aspnetcore.swagger

เปลี่ยนเส้นทางสำหรับจุดสิ้นสุดของ Swagger JSON

โดยค่าเริ่มต้น Swagger JSON จะถูกเปิดเผยในเส้นทางต่อไปนี้ - "/swagger/ {documentname }/swagger.json" หากจำเป็นคุณสามารถเปลี่ยนสิ่งนี้ได้เมื่อเปิดใช้งานมิดเดิลแวร์ Swagger เส้นทางที่กำหนดเองจะต้องรวมพารามิเตอร์ {documentName}

 app.useswagger (c => {c.routetemplate = "api-docs/{documentname}/swagger.json";})

หมายเหตุ: หากคุณใช้มิดเดิลแวร์ Swaggerui คุณจะต้องอัปเดตการกำหนดค่าเพื่อสะท้อนถึงจุดสิ้นสุดใหม่:

 app.useswaggerui (c => {c.swaggerendpoint ("/api-docs/v1/swagger.json", "my api v1");})

หมายเหตุ: หากคุณจำเป็นต้องอัปเดตเส้นทางสัมพัทธ์ที่ UI พร้อมใช้งานคุณจะต้องทำตามคำแนะนำที่พบในเส้นทางการเปลี่ยนแปลงที่สัมพันธ์กับ UI

ปรับเปลี่ยน Swagger ด้วยบริบทคำขอ

หากคุณต้องการตั้งค่าข้อมูลเมตาของ Swagger ตามคำขอปัจจุบันคุณสามารถกำหนดค่าตัวกรองที่ดำเนินการก่อนที่จะทำการจัดลำดับเอกสาร

 app.useswagger (c => {c.preserializefilters.add ((swagger, httpreq) => {swagger.servers = รายการใหม่ <mopeapiserver> {OpenApiserver ใหม่ {url = $ "{httpreq.scheme}: // host.value} "}};});});

OpenApiDocument และ HttpRequest ปัจจุบันทั้งคู่ผ่านไปยังตัวกรอง สิ่งนี้ให้ความยืดหยุ่นมาก ตัวอย่างเช่นคุณสามารถเพิ่มเซิร์ฟเวอร์ API ที่ชัดเจนตามส่วนหัว "โฮสต์" (ดังที่แสดง) หรือคุณสามารถตรวจสอบข้อมูลเซสชันหรือส่วนหัวการอนุญาตและลบการดำเนินการออกจากเอกสารตามสิทธิ์ของผู้ใช้

Serialize Swagger ในรูปแบบ 2.0

โดยค่าเริ่มต้น SwashBuckle จะสร้างและเปิดเผย Swagger JSON ในเวอร์ชัน 3.0 ของข้อกำหนดอย่างเป็นทางการเรียกว่าข้อกำหนด OpenAPI อย่างเป็นทางการ อย่างไรก็ตามเพื่อรองรับความเข้ากันได้ย้อนหลังคุณสามารถเลือกที่จะเปิดเผยต่อไปในรูปแบบ 2.0 ด้วยตัวเลือกต่อไปนี้:

 app.useswagger (c => {c.serializeaseasv2 = true;});

การทำงานกับไดเรกทอรีเสมือนจริงและพร็อกซีย้อนกลับ

ไดเรกทอรีเสมือนจริงและพร็อกซีย้อนกลับสามารถทำให้เกิดปัญหาสำหรับแอปพลิเคชันที่สร้างลิงก์และเปลี่ยนเส้นทางโดยเฉพาะอย่างยิ่งหากแอปส่งคืน URL ที่แน่นอน ตามส่วนหัว Host และข้อมูลอื่น ๆ จากคำขอปัจจุบัน เพื่อหลีกเลี่ยงปัญหาเหล่านี้ SwashBuckle ใช้ URL ที่สัมพันธ์กัน หากเป็นไปได้และส่งเสริมการใช้งานเมื่อกำหนดค่ามิดเดิลแวร์ Swaggerui และ REDOC

ตัวอย่างเช่นในการเชื่อมต่อมิดเดิลแวร์ Swaggerui คุณให้ URL ให้กับเอกสาร OpenAPI/Swagger หนึ่งฉบับหรือมากกว่า นี่คือ URL ที่ Swagger-Ui ซึ่งเป็นแอปพลิเคชันฝั่งไคลเอ็นต์จะเรียกร้องให้ดึงข้อมูลเมตา API ของคุณ เพื่อให้แน่ใจว่าสิ่งนี้ทำงานเบื้องหลังไดเรกทอรีเสมือนจริงและพร็อกซีย้อนกลับคุณควรแสดงความสัมพันธ์นี้กับ RoutePrefix ของ Swagger-ui เอง:

 app.useswaggerui (c => {c.routeprefix = "swagger"; c.swaggerendpoint ("v1/swagger.json", "my api v1");});

หมายเหตุ: ในเอกสารเวอร์ชันก่อนหน้าคุณอาจเห็นสิ่งนี้แสดงเป็นลิงค์ที่เกี่ยวข้องกับรูท (เช่น /swagger/v1/swagger.json ) สิ่งนี้จะไม่ทำงานหากแอปของคุณโฮสต์บนไดเรกทอรีเสมือนจริงของ IIS หรือหลังพร็อกซีที่ปิดบังเส้นทางการร้องขอก่อนส่งต่อ หากคุณเปลี่ยนไปใช้ไวยากรณ์ ที่เกี่ยวข้องกับหน้าเว็บ ที่แสดงด้านบนควรทำงานในทุกกรณี

ปรับแต่งวิธีการจัดทำเอกสาร OpenAPI

โดยค่าเริ่มต้น Swashbuckle จะทำให้เอกสาร OpenAPI เป็นอนุกรมโดยใช้วิธีการอนุกรมบนวัตถุเอกสาร OpenAPI หากต้องการการทำให้เป็นอนุกรมที่กำหนดเองเป็นไปได้ที่จะสร้างเอกสาร serializer ที่กำหนดเองที่ใช้อินเตอร์เฟส ISwaggerDocumentSerializer สามารถตั้งค่าบน SwaggerOptions ในคอลเลกชันบริการโดยใช้ ConfigureSwagger() :

บันทึก

หากคุณวางแผนที่จะใช้เครื่องมือบรรทัดคำสั่งเพื่อสร้างไฟล์ข้อกำหนด OpenAPI สิ่งนี้จะต้องทำในคอลเลกชันบริการโดยใช้ ConfigureSwagger()

 Services.configureswagger (ตัวเลือก => {optup.setCustomDocumentSerializer <CustomDocumentSerializer> ();})

เมื่อไม่ใช้เครื่องมือบรรทัดคำสั่งก็สามารถทำได้ในโฮสต์แอปพลิเคชัน:

 app.useSwagger (ตัวเลือก => {optures.setCustomDocumentSerializer <contivterdocumentserializer> ();})

swashbuckle.aspnetcore.swaggergen

กำหนด OperationIds ที่ชัดเจน

ใน Swagger การดำเนินงานอาจได้รับมอบหมายให้ operationId ID นี้จะต้องไม่ซ้ำกันในการดำเนินการทั้งหมดที่อธิบายไว้ใน API เครื่องมือและไลบรารี (เช่นเครื่องกำเนิดไคลเอนต์) อาจใช้ OperationID เพื่อระบุการดำเนินการที่ไม่ซ้ำกันดังนั้นจึงขอแนะนำให้ติดตามการประชุมการตั้งชื่อการเขียนโปรแกรมทั่วไป

การสร้าง ID อัตโนมัติที่ตรงกับข้อกำหนดเหล่านี้ในขณะที่ยังให้ชื่อที่มีความหมายในไลบรารีลูกค้าเป็นงานที่ไม่สำคัญดังนั้น Swashbuckle จะละเว้น operationId ตามค่าเริ่มต้น อย่างไรก็ตามหากจำเป็นคุณสามารถกำหนด operationIds ได้โดยการตกแต่งเส้นทางแต่ละเส้นทางหรือโดยการจัดทำกลยุทธ์ที่กำหนดเอง

ตัวเลือก 1) ตกแต่งเส้นทางด้วยคุณสมบัติ Name

 [httpget ("{id}", name = "getProductById")] สาธารณะ iActionResult รับ (int id) // erperationId = "getProductById"

ตัวเลือก 2) จัดทำกลยุทธ์ที่กำหนดเอง

 // startup.csservices.addswaggergen (c => {... // ใช้ชื่อวิธีการเป็น OperationId C.CustomoperationIds (apidesc => {return apidesc.trygetMethodinfo ) // ProductsController.cs [httpget ("{id}")] สาธารณะ iActionResult getProductById (ID int) // erperationId = "getProductById"

หมายเหตุ: ด้วยวิธีการใดวิธีหนึ่งผู้เขียน API มีหน้าที่รับผิดชอบในการรับรองความเป็นเอกลักษณ์ของ operationIds ในการดำเนินการทั้งหมด

รายการตอบสนองการดำเนินการ

โดยค่าเริ่มต้น SwashBuckle จะสร้างการตอบสนอง "200" สำหรับการดำเนินการแต่ละครั้ง หากการกระทำส่งคืนการตอบสนอง DTO สิ่งนี้จะถูกใช้เพื่อสร้างสคีมาสำหรับการตอบสนอง ตัวอย่างเช่น ...

 [httppost ("{id}")] ผลิตภัณฑ์สาธารณะ getById (int id)

จะสร้างข้อมูลเมตาตอบกลับต่อไปนี้: 

responses: {
  200: {
    description: "OK",
    content: {
      "application/json": {
        schema: {
          $ref: "#/components/schemas/Product"
        }
      }
    }
  }
}

คำตอบที่ชัดเจน

หากคุณต้องการระบุรหัสสถานะที่แตกต่างกันและ/หรือการตอบกลับเพิ่มเติมหรือการกระทำของคุณส่งคืน IActionResult แทนการตอบสนอง DTO คุณสามารถอธิบายการตอบสนองอย่างชัดเจนกับ ProducesResponseTypeAttribute ที่จัดส่งด้วย ASP.NET Core ตัวอย่างเช่น ...

 [httppost ("{id}")] [producesResponSetype (typeof (ผลิตภัณฑ์), 200)] [producesResponSetype (typeof (idictionary <string, string>), 400)]

จะสร้างข้อมูลเมตาตอบกลับต่อไปนี้: 

responses: {
  200: {
    description: "OK",
    content: {
      "application/json": {
        schema: {
          $ref: "#/components/schemas/Product"
        }
      }
    }
  },
  400: {
    description: "Bad Request",
    content: {
      "application/json": {
        schema: {
          type: "object",
          additionalProperties: {
            type: "string"
          }
        }
      }
    }
  },
  500: {
    description: "Internal Server Error",
    content: {}
  }
}

พารามิเตอร์ที่ต้องการและคุณสมบัติสคีมา

ในเอกสาร Swagger คุณสามารถตั้งค่าสถานะพารามิเตอร์และคุณสมบัติสคีมาที่จำเป็นสำหรับการร้องขอ หากพารามิเตอร์ (ระดับบนสุดหรืออิงคุณสมบัติ) ได้รับการตกแต่งด้วย BindRequiredAttribute หรือ RequiredAttribute SwashBuckle จะตั้งค่าสถานะเป็นพารามิเตอร์ "จำเป็น" ในพารามิเตอร์ที่สร้างขึ้นโดยอัตโนมัติ:

 // ProductsController.CSpublic IACTIONRESULT SECK ([FromQuery, BindRequired] คำหลักสตริง, [fromQuery] PagingParams PagingParams) {ถ้า (! ModelState.isvalid) กลับ Badrequest (ModelState); ] สาธารณะ int pageno {get; ชุด; } สาธารณะ int pageSize {get; ชุด; -

นอกเหนือจากพารามิเตอร์ Swashbuckle จะให้เกียรติ RequiredAttribute เมื่อใช้ในแบบจำลองที่ผูกพันกับร่างกายคำขอ ในกรณีนี้คุณสมบัติที่ตกแต่งจะถูกตั้งค่าสถานะเป็นคุณสมบัติ "จำเป็น" ในคำอธิบายของร่างกาย:

 // ProductsController.CSpublic iActionResult สร้าง ([frombody] ผลิตภัณฑ์ผลิตภัณฑ์) {ถ้า (! modelState.isvalid) ส่งคืน badrequest (ModelState); ... } // product.cspublic คลาสผลิตภัณฑ์ {[จำเป็น] ชื่อสตริงสาธารณะ {รับ; ชุด; } คำอธิบายสตริงสาธารณะ {get; ชุด; -

จัดการแบบฟอร์มและการอัปโหลดไฟล์

คอนโทรลเลอร์นี้จะยอมรับค่าฟิลด์แบบฟอร์มสองค่าและหนึ่งชื่ออัปโหลดไฟล์จากแบบฟอร์มเดียวกัน:

 [HTTPPOST] โมฆะสาธารณะ UploadFile ([Frorm] คำอธิบายสตริง, [frorform] dateTime clientdate, ไฟล์ iformfile)

หมายเหตุสำคัญ: ตามเอกสารหลักของ ASP.NET คุณไม่ควรตกแต่งพารามิเตอร์ IFormFile ด้วยแอตทริบิวต์ [FromForm] เป็นแหล่งรวมที่มีผลผูกพันโดยอัตโนมัติจากประเภท ในความเป็นจริงค่าที่อนุมานคือ BindingSource.FormFile และถ้าคุณใช้แอตทริบิวต์มันจะถูกตั้งค่าเป็น BindingSource.Form แทนซึ่งจะเพิ่ม ApiExplorer ซึ่งเป็นองค์ประกอบเมตาดาต้าที่จัดส่งด้วย ASP.NET Core และพึ่งพาอย่างหนัก ปัญหาหนึ่งที่นี่คือ Swaggerui จะไม่ปฏิบัติต่อพารามิเตอร์เป็นไฟล์และจะไม่แสดงปุ่มอัปโหลดไฟล์หากคุณรวมแอตทริบิวต์นี้โดยไม่ตั้งใจ

จัดการดาวน์โหลดไฟล์

ApiExplorer (ส่วนประกอบเมตาดาต้าหลักของ ASP.NET ที่ SwashBuckle ถูกสร้างขึ้น) ไม่ได้ ปรากฏขึ้นเป็นประเภท FileResult ตามค่าเริ่มต้นดังนั้นคุณต้องบอกอย่างชัดเจนกับแอตทริบิวต์ ProducesResponseType Produces

 [httpget ("{filename}")] [producesResponSetype (typeof (fileStreamResult), StatusCodes.status200ok, "image/jpeg")] public filestreamresult getFile

รวมคำอธิบายจากความคิดเห็น XML

เพื่อปรับปรุงเอกสารที่สร้างขึ้นด้วยคำอธิบายที่เป็นมิตรกับมนุษย์คุณสามารถใส่คำอธิบายประกอบการกระทำและแบบจำลองของคอนโทรลเลอร์ด้วยความคิดเห็น XML และกำหนดค่า Swashbuckle เพื่อรวมความคิดเห็นเหล่านั้นไว้ใน Swagger JSON:

  1. เปิดกล่องโต้ตอบคุณสมบัติสำหรับโครงการของคุณคลิกแท็บ "build" และตรวจสอบให้แน่ใจว่า "ไฟล์เอกสาร XML" ถูกตรวจสอบหรือเพิ่ม <GenerateDocumentationFile>true</GenerateDocumentationFile> องค์ประกอบไปยังส่วน <PropertyGroup> ของไฟล์โครงการ. csproj ของคุณ สิ่งนี้จะสร้างไฟล์ที่มีความคิดเห็น XML ทั้งหมดในเวลาที่สร้าง

    ณ จุดนี้คลาสหรือวิธีการใด ๆ ที่ไม่ได้ใส่คำอธิบายประกอบด้วยความคิดเห็น XML จะทำให้เกิดการเตือนการสร้าง หากต้องการระงับสิ่งนี้ให้ป้อนรหัสคำเตือน "1591" ลงในฟิลด์ "ระงับการเตือน" ในกล่องโต้ตอบคุณสมบัติหรือเพิ่ม <NoWarn>1591</NoWarn> ไปยังส่วน <PropertyGroup> ของไฟล์โครงการ. csproj ของคุณ

  2. กำหนดค่า swashbuckle เพื่อรวมความคิดเห็น XML ในไฟล์ลงใน Swagger JSON ที่สร้างขึ้น:

     services.addswaggergen (c => {c.swaggerdoc ("v1", ใหม่ openapiinfo {title = "my api - v1", เวอร์ชัน = "v1"}); c.includexmlcomments (แอสเซมบลี c.includexmlcomments (typeof (mycontroller) .assembly));}

  3. ใส่คำอธิบายประกอบการกระทำของคุณด้วยการสรุปข้อสังเกตพารามิเตอร์และแท็กการตอบกลับ:

     /// <summary> /// ดึงผลิตภัณฑ์เฉพาะโดย ID ที่ไม่ซ้ำกัน /// </summary> /// <ข้อสังเกต> ความยอดเยี่ยม! > รหัสผลิตภัณฑ์ </param> /// <response code = "200"> การดึงผลิตภัณฑ์ </response> /// <response code = "404"> ไม่พบผลิตภัณฑ์ </semplement> /// <response code = "500"> อ๊ะ! ไม่สามารถค้นหาผลิตภัณฑ์ของคุณได้ในขณะนี้ </serponse> [httpget ("{id}")] [producesresponsetype (typeof (ผลิตภัณฑ์), 200)] [ผลิต esprosStype (404)] id)

  4. นอกจากนี้คุณยังสามารถใส่คำอธิบายประกอบประเภทด้วยแท็กสรุปและตัวอย่าง:

     ผลิตภัณฑ์ระดับสาธารณะ {/// <summary> /// ชื่อของผลิตภัณฑ์ /// </summary> /// <pample> รองเท้าบาสเก็ตบอลผู้ชาย </except> ชื่อสตริงสาธารณะ {get; ชุด; } /// <summary> /// ปริมาณที่เหลืออยู่ในสต็อก /// </summary> /// <pample> 10 </expact> INT AvailableStock สาธารณะ {get; ชุด; } /// <summary> /// ขนาดของผลิตภัณฑ์มีอยู่ใน /// </summary> /// <pample> ["เล็ก", "สื่อ", "ใหญ่"] สตริง> ขนาด {get; ชุด; -

  5. สร้างโครงการของคุณใหม่เพื่ออัปเดตไฟล์ความคิดเห็น XML และนำทางไปยังจุดสิ้นสุดของ Swagger JSON โปรดทราบว่าคำอธิบายถูกแมปเข้ากับฟิลด์ Swagger ที่สอดคล้องกันอย่างไร

หมายเหตุ: คุณยังสามารถให้คำอธิบาย Swagger Schema โดยการใส่คำอธิบายประกอบโมเดล API ของคุณและคุณสมบัติของพวกเขาด้วยแท็กสรุป หากคุณมีไฟล์ความคิดเห็น XML หลายไฟล์ (เช่นไลบรารีแยกต่างหากสำหรับคอนโทรลเลอร์และรุ่น) คุณสามารถเรียกใช้วิธีการรวม XLComments หลายครั้งและพวกเขาทั้งหมดจะถูกรวมเข้ากับ Swagger JSON

ให้ข้อมูลเมตา Global API

นอกเหนือจาก "pathitems", "การดำเนินการ" และ "การตอบสนอง" ซึ่ง swashbuckle สร้างขึ้นสำหรับคุณ Swagger ยังรองรับข้อมูลเมตาทั่วโลก (ดู https://swagger.io/specification/#oasobject) ตัวอย่างเช่นคุณสามารถให้คำอธิบายแบบเต็มสำหรับ API ข้อกำหนดในการให้บริการหรือแม้แต่ข้อมูลการติดต่อและการออกใบอนุญาต:

 c.swaggerdoc ("v1", ใหม่ openapiinfo {title = "my api - v1", เวอร์ชัน = "v1", คำอธิบาย = "ตัวอย่าง API เพื่อสาธิต swashbuckle" /ข้อกำหนด "), ติดต่อ = ใหม่ openapicontact {name =" Joe Developer ", email =" [email protected] "}, ใบอนุญาต = ใหม่ openapilicense {name =" Apache 2.0 ", url = ใหม่ URI (" https: //www.apache.org/licenses/license-2.0.html ")}});

เคล็ดลับ: ใช้ Intellisense เพื่อดูว่ามีสาขาอื่นใดบ้าง

สร้างเอกสาร Swagger หลายฉบับ

ด้วยการตั้งค่าที่อธิบายไว้ข้างต้นเครื่องกำเนิดไฟฟ้าจะรวมการดำเนินการ API ทั้งหมดในเอกสาร Swagger เดียว อย่างไรก็ตามคุณสามารถสร้างเอกสารหลายฉบับหากจำเป็น ตัวอย่างเช่นคุณอาจต้องการเอกสารแยกต่างหากสำหรับ API แต่ละเวอร์ชันของคุณ ในการทำเช่นนี้เริ่มต้นด้วยการกำหนดเอกสาร Swagger หลายฉบับใน Startup.cs :

 services.addswaggergen (c => {c.swaggerdoc ("v1", ใหม่ openapiinfo {title = "my api - v1", เวอร์ชัน = "v1"}); c.swaggerdoc ("v2", ใหม่ openapiinfo {title = " my api - v2 ", version =" v2 "});})

จดบันทึกอาร์กิวเมนต์แรกไปที่ Swaggerdoc มันจะต้องเป็นชื่อที่เป็นมิตรกับ URI ที่ระบุเอกสารที่ไม่ซ้ำกัน ต่อมาก็ใช้เพื่อสร้างเส้นทางสำหรับการร้องขอ JSON Swagger ที่เกี่ยวข้อง ตัวอย่างเช่นด้วยการกำหนดเส้นทางเริ่มต้นเอกสารข้างต้นจะพร้อมใช้งานที่ "/swagger/v1/swagger.json" และ "/swagger/v2/swagger.json"

ถัดไปคุณจะต้องแจ้งให้ทราบว่าการกระทำใดที่จะรวมไว้ในเอกสารแต่ละฉบับ แม้ว่าสิ่งนี้สามารถปรับแต่งได้ (ดูด้านล่าง) โดยค่าเริ่มต้นเครื่องกำเนิดจะใช้คุณสมบัติ ApiDescription.GroupName ซึ่งเป็นส่วนหนึ่งของชั้นเมตาในตัวที่จัดส่งด้วย ASP.NET Core เพื่อสร้างความแตกต่างนี้ คุณสามารถตั้งค่าได้โดยการตกแต่งการกระทำของแต่ละบุคคลหรือโดยใช้การประชุมที่กว้างแอปพลิเคชัน

ตกแต่งการกระทำของแต่ละบุคคล

หากต้องการรวมการกระทำในเอกสาร Swagger ที่เฉพาะเจาะจงตกแต่งด้วย ApiExplorerSettingsAttribute และ set GroupName เป็นชื่อเอกสารที่เกี่ยวข้อง

 [httppost] [Apiexplorersettings (GroupName = "v2")] โมฆะสาธารณะโพสต์ ([frombody] ผลิตภัณฑ์ผลิตภัณฑ์)

กำหนดการกระทำให้กับเอกสารตามอนุสัญญา

ในการจัดกลุ่มตามการประชุมแทนการตกแต่งทุกการกระทำคุณสามารถใช้คอนโทรลเลอร์ที่กำหนดเองหรืออนุสัญญาแอ็คชั่น ตัวอย่างเช่นคุณสามารถเชื่อมต่ออนุสัญญาต่อไปนี้เพื่อกำหนดการกระทำให้กับเอกสารตามเนมสเปซคอนโทรลเลอร์

 // apiexplorergroupperversionconvention.cspublic คลาส apiexplorergroupperversionconvention: IcontrollerModelConvention {โมฆะสาธารณะใช้ (คอนโทรลเลอร์คอนโทรลเลอร์) // เช่น "controllers.v1" var apiversion = controllerNamespace.split ('.'). last (). toLower (); control.apiexplorer.groupname = apiversion;}} // startup.cspublic void configureservices services.addmvc (c => c.conventions.add (ใหม่ apiexplorergroupperversionconvention ())); ... }

ปรับแต่งกระบวนการเลือกการกระทำ

เมื่อเลือกการกระทำสำหรับเอกสาร Swagger ที่กำหนดเครื่องกำเนิดไฟฟ้าจะเรียกใช้ DocInclusionPredicate กับ ApiDescription ทุกตัวที่ปรากฏขึ้นโดยเฟรมเวิร์ก การใช้งานเริ่มต้นจะตรวจสอบ ApiDescription.GroupName และส่งคืนจริงหากค่าเป็นโมฆะหรือเท่ากับชื่อเอกสารที่ร้องขอ อย่างไรก็ตามคุณยังสามารถจัดเตรียมเพรดิเคตที่กำหนดเองได้ ตัวอย่างเช่นหากคุณใช้วิธีการอิงแอตทริบิวต์เพื่อใช้การกำหนดเวอร์ชัน API (เช่น Microsoft.aspNetCore.mvc.versioning) คุณสามารถกำหนดค่าพหุคูณที่กำหนดเองที่ใช้ประโยชน์จากแอตทริบิวต์เวอร์ชันแทน:

 C.DocinclusionPredicate ((docName, apidesc) => {ถ้า (! apidesc.trygetMethodinfo (methodInfo methodInfo)) ส่งคืน false; var version = methodInfo.declaringType .getCustomAtTributes (true) > attr.versions);

เปิดเผยเอกสารหลายฉบับผ่าน UI

หากคุณใช้มิดเดิลแวร์ SwaggerUI คุณจะต้องระบุจุดสิ้นสุดเพิ่มเติมใด ๆ ที่คุณต้องการเปิดเผย ดูรายการเอกสาร Swagger หลายฉบับสำหรับข้อมูลเพิ่มเติม

ละเว้นการดำเนินงานที่ล้าสมัยและ/หรือคุณสมบัติสคีมา

ข้อมูลจำเพาะ Swagger รวมถึงธง deprecated เพื่อระบุว่าการดำเนินการเลิกใช้แล้วและควรละเว้นจากการใช้งาน เครื่องกำเนิดไฟฟ้า swagger จะตั้งค่าสถานะนี้โดยอัตโนมัติหากการกระทำที่สอดคล้องกันได้รับการตกแต่งด้วย ObsoleteAttribute อย่างไรก็ตามแทนที่จะตั้งค่าสถานะคุณสามารถกำหนดค่าเครื่องกำเนิดไฟฟ้าให้ละเว้นการกระทำที่ล้าสมัยโดยสิ้นเชิง:

 services.addswaggergen (c => {... c.ignoreobsoleteactions ();};

วิธีการที่คล้ายกันสามารถใช้เพื่อละเว้นคุณสมบัติล้าสมัยจาก schemas ในเอาต์พุต swagger นั่นคือคุณสามารถตกแต่งคุณสมบัติของแบบจำลองได้ด้วย ObsoleteAttribute และกำหนดค่า swashbuckle เพื่อละเว้นคุณสมบัติเหล่านั้นเมื่อสร้าง schemas JSON:

 services.addswaggergen (c => {... c.ignoreobsoleteproperties ();};

ละเว้นการดำเนินงานโดยพลการ

คุณสามารถละเว้นการดำเนินการจากเอาท์พุท Swagger โดยการตกแต่งการกระทำของแต่ละบุคคลหรือโดยใช้การประชุมที่กว้างแอปพลิเคชัน

ตกแต่งการกระทำของแต่ละบุคคล

ApiExplorerSettingsAttribute ต้องการละเว้นการ IgnoreApi ที่เฉพาะ

 [httpget ("{id}")] [apiexplorersettings (molongelye = true)] ผลิตภัณฑ์สาธารณะ getById (int id)

ละเว้นการกระทำโดยอนุสัญญา

หากต้องการละเว้นการกระทำโดยการประชุมแทนที่จะตกแต่งเป็นรายบุคคลคุณสามารถใช้การประชุมแอ็คชั่นที่กำหนดเองได้ ตัวอย่างเช่นคุณสามารถเชื่อมต่อการประชุมต่อไปนี้เพื่อรับเอกสารได้รับการดำเนินการเท่านั้น:

 // apiexploretergetsonlyconvention.cspublic คลาส apiexplorgetsonlyconvention: iActionModelConvention {โมฆะสาธารณะใช้ (ActionModel Action) {action.apiexplorer.isvisible = action.attributes.ofType ection บริการ) {services.addmvc (c => c.conventions.add (ใหม่ apiexplorgetsonlyconvention ())));}

ปรับแต่งแท็กการทำงาน (เช่นสำหรับการจัดกลุ่ม UI)

ข้อมูลจำเพาะ Swagger อนุญาตให้มีการกำหนด "แท็ก" อย่างน้อยหนึ่งแท็กให้กับการดำเนินการ เครื่องกำเนิด Swagger จะกำหนดชื่อคอนโทรลเลอร์เป็นแท็กเริ่มต้น นี่เป็นสิ่งสำคัญที่ควรทราบหากคุณใช้มิดเดิลแวร์ SwaggerUI เนื่องจากใช้ค่านี้ในการดำเนินการกลุ่ม

คุณสามารถแทนที่แท็กเริ่มต้นโดยการจัดทำฟังก์ชั่นที่ใช้แท็กตามการประชุม ตัวอย่างเช่นการกำหนดค่าต่อไปนี้จะติดแท็กดังนั้นการดำเนินการกลุ่มใน UI โดยวิธี HTTP:

 services.addswaggergen (c => {... c.tagactionsby (api => api.httpmethod);};

เปลี่ยนลำดับการดำเนินการเรียงลำดับ (เช่นสำหรับการเรียงลำดับ UI)

โดยค่าเริ่มต้นการดำเนินการจะถูกสั่งซื้อโดยแท็กที่ได้รับมอบหมาย (ดูด้านบน) ก่อนที่พวกเขาจะถูกจัดกลุ่มลงในโครงสร้างที่เป็นศูนย์กลางและซ้อนกันของสเป็ค swagger แต่คุณสามารถเปลี่ยนการสั่งซื้อเริ่มต้นของการกระทำด้วยกลยุทธ์การเรียงลำดับที่กำหนดเอง:

 Services.addswaggergen (c => {... C.OrderActionSby ((apidesc) => $ "{apidesc.actionDescriptor.routevalues ​​[" คอนโทรลเลอร์ "]} _ {apidesc.httpmethod}");};

หมายเหตุ: สิ่งนี้กำหนดลำดับการเรียงลำดับก่อนการดำเนินการจะถูกจัดกลุ่มและแปลงเป็นรูปแบบ Swagger ดังนั้นจึงส่งผลกระทบต่อการสั่งซื้อของกลุ่ม (เช่น Swagger "pathitems") และการสั่งซื้อของการดำเนินการภายในกลุ่มในเอาท์พุท Swagger

ปรับแต่ง Schema ID

หากเครื่องกำเนิดไฟฟ้าเผชิญหน้ากับพารามิเตอร์หรือประเภทการตอบสนองที่ซับซ้อนมันจะสร้างสคีมา JSON ที่สอดคล้องกันให้เพิ่มลงในพจนานุกรม components/schemas ทั่วโลกและอ้างอิงจากคำอธิบายการดำเนินการตาม ID ที่ไม่ซ้ำกัน ตัวอย่างเช่นหากคุณมีการดำเนินการที่ส่งคืนประเภท Product สคีมาที่สร้างขึ้นจะถูกอ้างอิงดังนี้: 

responses: {
  200: {
    description: "OK",
    content: {
      "application/json": {
        schema: {
          $ref: "#/components/schemas/Product"
        }
      }
    }
  }
}

อย่างไรก็ตามหากพบหลายประเภทที่มีชื่อเดียวกัน แต่เนมสเปซที่แตกต่างกัน (เช่น RequestModels.Product & ResponseModels.Product ) จากนั้น Swashbuckle จะเพิ่มข้อยกเว้นเนื่องจาก "schemaids ที่ขัดแย้งกัน" ในกรณีนี้คุณจะต้องจัดทำกลยุทธ์ ID ที่กำหนดเองซึ่งมีคุณสมบัติเพิ่มเติมชื่อ:

 Services.addswaggergen (c => {... C.CustomsChemaids ((ประเภท) => type.fullName);};

ดู #2703 สำหรับการสนับสนุนประเภทซ้อน

แทนที่สคีมาสำหรับประเภทเฉพาะ

Swashbuckle ทำงานได้ดีในการสร้าง Schemas JSON ที่อธิบายคำขอและการตอบกลับของคุณอย่างแม่นยำ อย่างไรก็ตามหากคุณกำลังปรับแต่งพฤติกรรมการทำให้เป็นอนุกรมสำหรับบางประเภทใน API ของคุณคุณอาจต้องช่วยมัน

ตัวอย่างเช่นคุณอาจมีคลาสที่มีคุณสมบัติหลายอย่างที่คุณต้องการแสดงใน JSON เป็นสตริงที่คั่นด้วยเครื่องหมายจุลภาค ในการทำเช่นนี้คุณอาจใช้ JsonConverter ที่กำหนดเอง ในกรณีนี้ Swashbuckle ไม่ทราบว่าตัวแปลงถูกนำไปใช้อย่างไรและคุณจะต้องจัดเตรียมสคีมาที่อธิบายประเภทได้อย่างแม่นยำ:

 // phonenumber.cspublic คลาส phonenumber {public string countrycode {get; ชุด; } String Public String พื้นที่ {get; ชุด; } public String subscriberid {get; ชุด; }} // startup.csservices.addswaggergen (c => {... C.MapType <Phonenumber> (() => OpenApischema ใหม่ {type = "String"});};

ขยายเครื่องกำเนิดไฟฟ้าด้วยการทำงานตัวกรอง schema & document

Swashbuckle เปิดเผยไปป์ไลน์ตัวกรองที่เชื่อมต่อกับกระบวนการสร้าง เมื่อสร้างขึ้นแล้ววัตถุข้อมูลเมตาแต่ละรายการจะถูกส่งผ่านไปยังไปป์ไลน์ซึ่งสามารถแก้ไขได้เพิ่มเติม คุณสามารถเชื่อมต่อตัวกรองที่กำหนดเองเพื่อเพิ่ม "การดำเนินการ" ที่สร้างขึ้น "schemas" และ "เอกสาร"

ตัวกรองการดำเนินการ

Swashbuckle ดึง ApiDescription ซึ่งเป็นส่วนหนึ่งของ ASP.NET Core สำหรับทุกการกระทำและใช้เพื่อสร้าง OpenApiOperation ที่สอดคล้องกัน เมื่อสร้างขึ้นแล้วจะผ่าน OpenApiOperation และ ApiDescription ผ่านรายการตัวกรองการดำเนินการที่กำหนดค่า

ในการใช้งานตัวกรองทั่วไปคุณจะตรวจสอบ ApiDescription สำหรับข้อมูลที่เกี่ยวข้อง (เช่นข้อมูลเส้นทางแอตทริบิวต์การดำเนินการ ฯลฯ ) จากนั้นอัปเดต OpenApiOperation ตาม ตัวอย่างเช่นตัวกรองต่อไปนี้แสดงการตอบสนอง "401" เพิ่มเติมสำหรับการกระทำทั้งหมดที่ตกแต่งด้วย AuthorizeAttribute :

 // AuthresponsesOperationFilter.CSpublic AuthresponsesOperationFilter: iOperationFilter {โมฆะสาธารณะใช้ <Authorizeattribute > (); ถ้า (Authattributes.any ()) Operation.responses.add ("401", OpenApiresponse ใหม่ {คำอธิบาย = "ไม่ได้รับอนุญาต"});}} // startup.csservices.addswaggergen (c => {... ... C.OperationFilter <AuthResponsEsOperationFilter> ();};

หมายเหตุ: ท่อกรองเป็น Di-Aware นั่นคือคุณสามารถสร้างตัวกรองด้วยพารามิเตอร์ตัวสร้างและหากประเภทพารามิเตอร์ได้รับการลงทะเบียนกับเฟรมเวิร์ก DI พวกเขาจะถูกฉีดโดยอัตโนมัติเมื่อฟิลเตอร์ถูกสร้างอินสแตนซ์

ตัวกรองสคีมา

Swashbuckle สร้าง JSonschema ที่ปรุงรสที่มีรสชาติสำหรับพารามิเตอร์การตอบสนองและประเภทคุณสมบัติทุกประเภทที่สัมผัสโดยการกระทำของคอนโทรลเลอร์ของคุณ เมื่อสร้างขึ้นแล้วจะผ่านสคีมาและพิมพ์ผ่านรายการตัวกรองสคีมาที่กำหนดค่าไว้

ตัวอย่างด้านล่างเพิ่มส่วนขยายของผู้ขายอัตโนมัติ (ดู https://github.com/azure/autorest/blob/master/docs/extensions/readme.md#x-ms-enum) เพื่อแจ้งเครื่องมืออัตโนมัติ เมื่อสร้างไคลเอนต์ API

 // autorestschemafilter.cspublic คลาส autorestschemafilter: ischemafilter {โมฆะสาธารณะใช้ (Openapischema schema, schemafiltercontext บริบท) {var type = context.type; if (type.isenum) {schema.extensions.add ( openapiobject {["name"] = ใหม่ openapistring (type.name), ["modelasstring"] = ใหม่ openapiboolean (จริง)});};}} // startup.csservices.addswaggergen (c => {... c .Schemafilter <AutorestSchemafilter> ();};

ตัวอย่างด้านล่างอนุญาตให้สร้างสคีมาอัตโนมัติของ Dictionary<Enum, TValue> วัตถุ โปรดทราบว่าสิ่งนี้สร้างเพียงการผยองเท่านั้น System.Text.Json ไม่สามารถแยกพจนานุกรม enums ได้โดยค่าเริ่มต้นดังนั้นคุณจะต้องใช้ JsonConverter พิเศษเช่นในเอกสาร. NET

 // dictionarytkeyenumtvalueschemafilter.cspublic Class Dictionarytkeyenumtvalueschemafilter: ischemafilter {
  ใช้โมฆะสาธารณะ (OpenApischema Schema, บริบท schemafiltercontext)
  {// ใช้เฉพาะฟิลด์ที่เป็นพจนานุกรม <enum, tvalue> ถ้า (! context.type.isgenerictype ||! context.type.getenerictypedefinition (). isAssignablefrom (typeof (พจนานุกรม <,>)))) {return;} var keyType = context.type.getGenericArguments () [0]; var valuetype = context.type.getGenericArguments () [1]; ถ้า (! keyType.isenum) {return;} schema.type = "Object"; schema.properties = keyType.getEnumNames (). todictionary (ชื่อ => ชื่อ, ชื่อ => context.schemagenerator.generateReSchema (valuetype, context.schemarepository));
  }} // startup.csservices.addswaggergen (c => {... // สิ่งเหล่านี้จะถูกแทนที่ด้วย dictionarytkeyenumtvalueschemafilter แต่จำเป็นต้องหลีกเลี่ยงข้อผิดพลาด // คุณจะต้องใช้หนึ่งสำหรับพจนานุกรมทุกชนิด <,> คุณมี .C.MapType <พจนานุกรม <myenum, รายการ <String>>> (() => ใหม่ openapischema ()); C.Schemafilter <Dictionarytkeyenumtvalueschemafilter> ();};

ตัวกรองเอกสาร

เมื่อมีการสร้าง OpenApiDocument แล้วมันก็สามารถส่งผ่านชุดของตัวกรองเอกสารที่กำหนดค่าไว้ล่วงหน้าได้เช่นกัน สิ่งนี้ให้การควบคุมเต็มรูปแบบเพื่อแก้ไขเอกสารตามที่คุณเห็นว่าเหมาะสม เพื่อให้แน่ใจว่าคุณยังคงส่งคืน JSON ที่ถูกต้องคุณควรอ่านผ่านข้อกำหนดก่อนใช้ประเภทตัวกรองนี้

ตัวอย่างด้านล่างให้คำอธิบายสำหรับแท็กใด ๆ ที่กำหนดให้กับการดำเนินการในเอกสาร:

 Public Class TagdescriptionsDocumentFilter: IdocumentFilter {โมฆะสาธารณะใช้ (OpenApidocument Swaggerdoc, DocumentFilterContext บริบท) {Swaggerdoc.tags = รายการใหม่ <mopeapitag> {OpenApitag ใหม่ {name = "ผลิตภัณฑ์" {name = "คำสั่งซื้อ", คำอธิบาย = "ส่งคำสั่งซื้อ"}};}}

หมายเหตุ: หากคุณใช้มิดเดิลแวร์ของ SwaggerUI TagDescriptionsDocumentFilter ที่แสดงด้านบนสามารถนำมาใช้เพื่อแสดงคำอธิบายเพิ่มเติมข้างการดำเนินการแต่ละกลุ่ม

เพิ่มคำจำกัดความและข้อกำหนดด้านความปลอดภัย

ใน Swagger คุณสามารถอธิบายได้ว่า API ของคุณมีความปลอดภัยอย่างไรโดยการกำหนดแผนการรักษาความปลอดภัยอย่างน้อยหนึ่งรูปแบบ (เช่นพื้นฐาน, API Key, OAuth2 ฯลฯ ) และประกาศว่าแผนการเหล่านั้นจะใช้งานได้ทั่วโลกหรือสำหรับการดำเนินงานเฉพาะ สำหรับรายละเอียดเพิ่มเติมดูที่วัตถุข้อกำหนดด้านความปลอดภัยในสเป็ค Swagger ..

ใน Swashbuckle คุณสามารถกำหนดแผนการได้โดยการเรียกใช้วิธี AddSecurityDefinition ของการกำหนดชื่อและอินสแตนซ์ของ OpenApiSecurityScheme ตัวอย่างเช่นคุณสามารถกำหนด OAuth 2.0 - การไหลโดยนัยดังนี้:

 // startup.csservices.addswaggergen (c => {... // กำหนดรูปแบบ OAuth2.0 ที่ใช้งานอยู่ ใหม่ openapioauthflows {implict = ใหม่ openapioauthflow {AuthorizationUrl = ใหม่ URI ("/Auth-Server/Connect/Authorize", urikind.Relative), ขอบเขต = พจนานุกรมใหม่ <String, String> {{"readAccess" , {"WriteAccess", "Access Write Operations"}}}}});};

หมายเหตุ: นอกเหนือจากการกำหนดรูปแบบแล้วคุณต้องระบุว่าการดำเนินการใดที่ใช้บังคับ คุณสามารถใช้แผนการทั่วโลก (เช่นการดำเนินงานทั้งหมด) ผ่านวิธี AddSecurityRequirement ตัวอย่างด้านล่างแสดงให้เห็นว่าโครงการที่เรียกว่า "OAuth2" ควรใช้กับการดำเนินการทั้งหมดและจำเป็นต้องใช้ขอบเขต "readaccess" และ "writeaccess" เมื่อใช้แผนการประเภทอื่นที่ไม่ใช่ "OAuth2" อาร์เรย์ของขอบเขตจะต้องว่างเปล่า

 C.Addswaggergen (c => {... C.AddSecurityRequirement (ใหม่ OpenApisecurityRequirement {{ใหม่ OpenApisecurityScheme {reference = new OpenApireference {type = referenCetype.securityScheme, id = "oauth2"}}, ใหม่ [] writeaccess "}}});})

หากคุณมีแผนการที่ใช้ได้กับการดำเนินการบางอย่างเท่านั้นคุณสามารถนำไปใช้กับตัวกรองการดำเนินการ ตัวอย่างเช่นตัวกรองต่อไปนี้จะเพิ่มข้อกำหนด OAuth2 ตามการมีอยู่ของ AuthorizeAttribute :

 // SecurityRequirementsOperationFilter.CSpublic ระดับความปลอดภัย REQUIREMENTOUREMENTOUREMENTOURETIONFILTER: iOperationFilter {โมฆะสาธารณะใช้ (OpenApioperation Operation, OperationFilterContext บริบท) {// ชื่อนโยบายแผนที่ > attr.policy) .distinct (); ถ้า (จำเป็นต้องใช้ spopes.any ()) {erperation.responses.add ("401", OpenApiresponse ใหม่ {คำอธิบาย = "ไม่ได้รับอนุญาต"}); Operation.responses.add ("403", ใหม่ openApiresponse {คำอธิบาย = "ต้องห้าม"}); var oauthscheme = ใหม่ openapisecurityscheme {referent = new OpenApireference {type = referencetype.SecurityScheme, id = "oauth2"}}; การดำเนินการ oauthscheme] = ecteduelscopes.tolist ()}};}}}}

หมายเหตุ: หากคุณใช้มิดเดิลแวร์ SwaggerUI คุณสามารถเปิดใช้งานการไหลของ OAuth2.0 แบบโต้ตอบที่ใช้พลังงานจากข้อมูลเมตาการรักษาความปลอดภัยที่ปล่อยออกมา ดูการเปิดใช้งาน OAuth2.0 สำหรับรายละเอียดเพิ่มเติม

เพิ่มคำจำกัดความและข้อกำหนดด้านความปลอดภัยสำหรับผู้ถือ Auth

 services.addswaggergen (c => {c.addsecurityDefinition ("bearerauth", OpenApisecurityScheme ใหม่ {type = securitySchemetype.http, scheme = "ผู้ถือ", ผู้ถือ = "JWT", คำอธิบาย = "JWT );

มรดกและความหลากหลาย

Swagger / OpenAPI กำหนดคำหลัก allOf และ oneOf คำหลักสำหรับการอธิบายความสัมพันธ์การสืบทอดและความหลากหลายในคำจำกัดความสคีมา ตัวอย่างเช่นหากคุณใช้คลาสพื้นฐานสำหรับโมเดลที่ใช้คุณสมบัติทั่วไปคุณสามารถใช้คำหลัก allOf เพื่ออธิบายลำดับชั้นการสืบทอด หรือหาก serializer ของคุณรองรับ polymorphic serialization/deserialization คุณสามารถใช้คำหลัก oneOf เพื่อจัดทำเอกสาร schemas "ที่เป็นไปได้" ทั้งหมดสำหรับการร้องขอ/การตอบกลับที่แตกต่างกันไปตามชนิดย่อย

การเปิดใช้งานมรดก

โดยค่าเริ่มต้นลำดับชั้นมรดกแบบแบนราบ นั่นคือสำหรับแบบจำลองที่ได้รับคุณสมบัติที่สืบทอดมานั้นรวมอยู่ในรายการและรายการที่ประกาศไว้ สิ่งนี้สามารถทำให้เกิดการทำซ้ำจำนวนมากใน Swagger ที่สร้างขึ้นโดยเฉพาะอย่างยิ่งเมื่อมีหลายชนิดย่อย นอกจากนี้ยังเป็นปัญหาหากคุณใช้ตัวสร้างไคลเอนต์ (เช่น NSWAG) และต้องการรักษาลำดับชั้นการสืบทอดในโมเดลไคลเอนต์ที่สร้างขึ้น ในการแก้ไขปัญหานี้คุณสามารถใช้การตั้งค่า UseAllOfForInheritance และสิ่งนี้จะใช้ประโยชน์จากคำหลัก allOf เพื่อรวมคุณสมบัติที่สืบทอดมาโดยการอ้างอิงใน Swagger ที่สร้างขึ้น: 

Circle: {
  type: "object",
  allOf: [
    {
      $ref: "#/components/schemas/Shape"
    }
  ],
  properties: {
    radius: {
      type: "integer",
      format: "int32",
    }
  },
},
Shape: {
  type: "object",
  properties: {
    name: {
      type: "string",
      nullable: true,
    }
  },
}

การเปิดใช้งาน polymorphism

หาก serializer ของคุณรองรับ polymorphic serialization/deserialization และคุณต้องการแสดงรายการชนิดย่อยที่เป็นไปได้สำหรับการกระทำที่ยอมรับ/ส่งคืนประเภทฐานนามธรรมคุณสามารถใช้การตั้งค่า UseOneOfForPolymorphism ดังนั้น Schemas คำขอ/การตอบกลับที่สร้างขึ้นจะอ้างอิงชุดของ schemas "ที่เป็นไปได้" แทนที่จะเป็นเพียงสคีมาคลาสพื้นฐาน: 

requestBody: {
  content: {
    application/json: {
      schema: {
      oneOf: [
        {
          $ref: "#/components/schemas/Rectangle"
        },
        {
          $ref: "#/components/schemas/Circle"
        },
      ],
    }
  }
}

การตรวจจับชนิดย่อย

ในฐานะที่เป็นความสัมพันธ์ที่สืบทอดและความหลากหลายมักจะซับซ้อนไม่เพียง แต่ในแบบจำลองของคุณเอง แต่ยังอยู่ในห้องสมุดคลาส. NET Swashbuckle ได้รับการคัดเลือกเกี่ยวกับลำดับชั้นที่ทำและไม่เปิดเผยใน Swagger ที่สร้างขึ้น โดยค่าเริ่มต้นมันจะรับชนิดย่อยใด ๆ ที่กำหนดไว้ในแอสเซมบลีเดียวกันกับประเภทฐานที่กำหนด หากคุณต้องการแทนที่พฤติกรรมนี้คุณสามารถให้ฟังก์ชั่นตัวเลือกที่กำหนดเอง:

 Services.addswaggergen (c => {... C.UseAllOfForInherItance (); C.SelectSubTypesusing (basetype => {return typeof (เริ่มต้น) .assembly.getTypes () โดยที่ (type => type.issubclassof (basetype)); })});

หมายเหตุ: หากคุณใช้ไลบรารีคำอธิบายประกอบ Swashbuckle มันมีตัวเลือกที่กำหนดเองซึ่งขึ้นอยู่กับการปรากฏตัวของแอตทริบิวต์ SwaggerSubType ในคำจำกัดความคลาสพื้นฐาน ด้วยวิธีนี้คุณสามารถใช้แอตทริบิวต์ง่ายๆเพื่อแสดงรายการความสัมพันธ์การสืบทอดและ/หรือ polymorphism ที่คุณต้องการเปิดเผยอย่างชัดเจน หากต้องการเปิดใช้งานพฤติกรรมนี้ให้ตรวจสอบเอกสารคำอธิบายประกอบ

อธิบายการเลือกปฏิบัติ

เมื่อใช้ร่วมกับคำหลัก oneOf และ / หรือ allOf , Swagger / OpenAPI รองรับฟิลด์ discriminator บนคำจำกัดความพื้นฐานสคีมา คำหลักนี้ชี้ไปที่คุณสมบัติที่ระบุประเภทเฉพาะที่แสดงโดยน้ำหนักบรรทุกที่กำหนด นอกเหนือจากชื่อคุณสมบัติแล้วคำอธิบาย discriminator อาจรวมถึง mapping ซึ่งแมปค่า discriminator กับคำจำกัดความสคีมาเฉพาะ

ตัวอย่างเช่น Newtonsoft serializer รองรับ polymorphic serialization/deserialization โดยการปล่อย/ยอมรับคุณสมบัติ "$ type" ในอินสแตนซ์ JSON ค่าของคุณสมบัตินี้จะเป็นชื่อประเภทที่ผ่านการรับรองของแอสเซมบลีของประเภทที่แสดงโดยอินสแตนซ์ JSON ที่กำหนด ดังนั้นเพื่ออธิบายพฤติกรรมนี้อย่างชัดเจนใน Swagger คำขอ/การตอบสนองที่สอดคล้องกันสามารถกำหนดได้ดังนี้: 

components: {
  schemas: {
    Shape: {
      required: [
        "$type"
      ],
      type: "object",
      properties: {
        $type: {
          type": "string"
      },
      discriminator: {
        propertyName: "$type",
        mapping: {
          Rectangle: "#/components/schemas/Rectangle",
          Circle: "#/components/schemas/Circle"
        }
      }
    },
    Rectangle: {
      type: "object",
      allOf: [
        {
          "$ref": "#/components/schemas/Shape"
        }
      ],
      ...
    },
    Circle: {
      type: "object",
      allOf: [
        {
          "$ref": "#/components/schemas/Shape"
        }
      ],
      ...
    }
  }
}

หากการเปิดใช้งาน UseAllOfForInheritance หรือ UseOneOfForPolymorphism และ serializer ของคุณรองรับ (และเปิดใช้งาน) การเปล่ง/ยอมรับคุณสมบัติการแยกแยะจากนั้น SwashBuckle จะสร้างข้อมูลเมตา discriminator ที่สอดคล้องกันโดยอัตโนมัติ

อีกทางเลือกหนึ่งหากคุณได้ปรับแต่ง serializer ของคุณเพื่อรองรับ polymorphic serialization/deserialization คุณสามารถให้ฟังก์ชั่นตัวเลือกที่กำหนดเองบางอย่างเพื่อกำหนดชื่อ discriminator และการแมปที่เกี่ยวข้อง:

 Services.addswaggergen (c => {... C.useoneofforinheritance (); C.SelectDiscriminatorNameusing ((basetype) => "typename"); c.SelectDisInatorValueusing ((ชนิดย่อย) => subtype.name);};

หมายเหตุ: หากคุณใช้ไลบรารีคำอธิบายประกอบ Swashbuckle มันมีฟังก์ชั่นตัวเลือกที่กำหนดเองซึ่งขึ้นอยู่กับการปรากฏตัวของ SwaggerDiscriminator และ SwaggerSubType ในคำจำกัดความของคลาสพื้นฐาน ด้วยวิธีนี้คุณสามารถใช้แอตทริบิวต์ง่ายๆเพื่อให้ข้อมูลเมตา discriminator อย่างชัดเจน หากต้องการเปิดใช้งานพฤติกรรมนี้ให้ตรวจสอบเอกสารคำอธิบายประกอบ

swashbuckle.aspnetcore.swaggerui

เปลี่ยนเส้นทางสัมพัทธ์เป็น UI

โดยค่าเริ่มต้น UI Swagger จะถูกเปิดเผยที่ "/Swagger" หากจำเป็นคุณสามารถเปลี่ยนสิ่งนี้ได้เมื่อเปิดใช้งานมิดเดิลแวร์ Swaggerui:

 app.useswaggerui (c => {c.routeprefix = "api-docs"}

เปลี่ยนชื่อเอกสาร

โดยค่าเริ่มต้น UI Swagger จะมีชื่อเอกสารทั่วไป เมื่อคุณเปิดหน้าหลายหน้าอาจเป็นเรื่องยากที่จะบอกพวกเขาออกจากกัน คุณสามารถเปลี่ยนแปลงสิ่งนี้ได้เมื่อเปิดใช้งานมิดเดิลแวร์ Swaggerui:

 app.useswaggerui (c => {c.documentTitle = "my swagger ui";}

เปลี่ยนเส้นทาง CSS หรือ JS

โดยค่าเริ่มต้น UI Swagger รวม CSS และ JS เริ่มต้น แต่ถ้าคุณต้องการเปลี่ยนเส้นทางหรือ URL (ตัวอย่างเช่นการใช้ CDN):

 app.useswaggerui (c => {c.stylespath = "https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/5.17.10/swagger-ui.min.css" : //cdnjs.cloudflare.com/ajax/libs/swagger-ui/5.17.10/swagger-ui-bundle.min.js "; /swagger-ui/5.17.10/swagger-ui-standalone-preset.min.js ";}

แสดงรายการเอกสาร Swagger หลายฉบับ

เมื่อเปิดใช้งานมิดเดิลแวร์คุณจะต้องระบุจุดสิ้นสุดของ Swagger หนึ่งจุดขึ้นไป (มีคุณสมบัติครบถ้วนหรือสัมพันธ์กับหน้า UI) เพื่อเพิ่มพลังงาน UI หากคุณให้จุดสิ้นสุดหลายจุดพวกเขาจะอยู่ในมุมขวาบนของหน้าเพื่อให้ผู้ใช้สลับระหว่างเอกสารที่แตกต่างกัน ตัวอย่างเช่นการกำหนดค่าต่อไปนี้สามารถใช้เพื่อจัดทำเอกสาร API เวอร์ชันที่แตกต่างกัน

 app.useswaggerui (c => {c.swaggerendpoint ("/swagger/v1/swagger.json", "v1 docs"); c.swaggerendpoint ("/swagger/v2/swagger.json", "v2 docs"); }

ใช้พารามิเตอร์ Swagger-UI

Swagger-Ui จัดส่งพารามิเตอร์การกำหนดค่าของตัวเองทั้งหมดที่อธิบายไว้ที่นี่ ใน Swashbuckle สิ่งเหล่านี้ส่วนใหญ่ปรากฏขึ้นผ่านตัวเลือกมิดเดิลแวร์ Swaggerui:

 app.useswaggerui (c => {c.defaultModelexpandDepth (2); C.DefaultModelRendering (ModelRendering.model); C.DefaultModelsexpandDepth (-1); ไม่มี) c.enabledeeplinking (); ["Mycustomplugin"]; ) => {ตอบกลับ;} ");});

บันทึก

เมื่อเพิ่มปลั๊กอินที่กำหนดเองตรวจสอบให้แน่ใจว่าคุณเพิ่มไฟล์ js ที่กำหนดเองที่กำหนดฟังก์ชันปลั๊กอิน

ฉีดจาวาสคริปต์ที่กำหนดเอง

ในการปรับแต่งพฤติกรรมคุณสามารถฉีดไฟล์ JavaScript เพิ่มเติมได้โดยเพิ่มลงในโฟลเดอร์ wwwroot ของคุณและระบุเส้นทางสัมพัทธ์ในตัวเลือกมิดเดิลแวร์:

 app.useswaggerui (c => {c.injectJavaVascript ("/swagger-ui/custom.js");}

หมายเหตุ: ตัวเลือก InjectOnCompleteJavaScript และ InjectOnFailureJavaScript ได้ถูกลบออกเนื่องจาก Swagger-Ui เวอร์ชันล่าสุดไม่ได้เปิดเผยตะขอที่จำเป็น แต่จะมีระบบปรับแต่งที่ยืดหยุ่นตามแนวคิดและรูปแบบจาก React และ Redux ในการใช้ประโยชน์จากสิ่งนี้คุณจะต้องจัดทำ index.html เวอร์ชันที่กำหนดเองตามที่อธิบายไว้ด้านล่าง

แอพตัวอย่างดัชนีที่กำหนดเองแสดงให้เห็นถึงวิธีการนี้โดยใช้ระบบปลั๊กอิน Swagger-UI ให้บริการ topbar ที่กำหนดเองและเพื่อซ่อนส่วนประกอบข้อมูล

ฉีด CSS ที่กำหนดเอง

ในการปรับแต่งรูปลักษณ์และความรู้สึกคุณสามารถฉีดสไตล์ CSS เพิ่มเติมได้โดยเพิ่มลงในโฟลเดอร์ wwwroot ของคุณและระบุเส้นทางสัมพัทธ์ในตัวเลือกมิดเดิลแวร์:

 app.useswaggerui (c => {c.injectstylesheet ("/swagger-ui/custom.css");}

ปรับแต่ง index.html

ในการปรับแต่ง UI นอกเหนือจากตัวเลือกพื้นฐานที่ระบุไว้ข้างต้นคุณสามารถจัดเตรียมหน้า Swagger-UI index.html เวอร์ชันของคุณเอง:

 app.useswaggerui (c => {c.indexstream = () => getType (). แอสเซมบลี. getManifestresourceStream ("customuiindex.swagger.index.html"); // ต้องการไฟล์ที่จะเพิ่มเป็นทรัพยากรที่ฝังตัว});

ในการเริ่มต้นใช้งานคุณควรยึด index.html ที่กำหนดเองของคุณในเวอร์ชันเริ่มต้น

เปิดใช้งาน OAUTH2.0 FLOWS

Swagger-Ui ได้รับการสนับสนุนในตัวเพื่อเข้าร่วมในการไหลของการอนุญาต OAuth2.0 มันโต้ตอบกับการอนุญาตและ/หรือจุดสิ้นสุดโทเค็นตามที่ระบุไว้ใน Swagger JSON เพื่อรับโทเค็นการเข้าถึงสำหรับการโทร API ที่ตามมา ดูการเพิ่มคำจำกัดความและข้อกำหนดด้านความปลอดภัยสำหรับตัวอย่างของการเพิ่ม Metadata OAuth2.0 ลงใน Swagger ที่สร้างขึ้น

หากจุดสิ้นสุดของ Swagger ของคุณมีข้อมูลเมตารักษาความปลอดภัยที่เหมาะสมการโต้ตอบ UI ควรเปิดใช้งานโดยอัตโนมัติ อย่างไรก็ตามคุณสามารถปรับแต่งการสนับสนุน OAUTH เพิ่มเติมใน UI ด้วยการตั้งค่าต่อไปนี้ด้านล่าง ดูเอกสาร Swagger-UI สำหรับข้อมูลเพิ่มเติม:

 app.useswaggerui (c => {c.oauthclientid ("test-id"); c.oauthclientsecret ("ทดสอบ-secret"); c.oauthusername ("ทดสอบผู้ใช้"); ); สตริง> {{"foo", "bar"}});

ใช้คำขอฝั่งไคลเอ็นต์และตัวดักตอบตอบกลับ

ในการใช้ตัวดักจับแบบกำหนดเองตามคำขอและการตอบกลับที่ต้องผ่าน Swagger-Ui คุณสามารถกำหนดได้เป็นฟังก์ชั่น JavaScript ในการกำหนดค่า:

 app.useswaggerui (c => {c.userequestinterceptor ("(req) => {req.headers ['x-my-custom-header'] = 'mycustomValue'; return req;}"); (res) => {console.log ('Interceptor ที่ถูกสกัดกั้นการตอบสนองจาก:', res.url);

สิ่งนี้มีประโยชน์ในช่วงของสถานการณ์ที่คุณอาจต้องการผนวกโทเค็น XSRF ในพื้นที่เข้ากับคำขอทั้งหมดเช่น:

 app.useswaggerui (c => {c.userequestinterceptor ("(req) => {req.headers ['x-xsrf-token'] = localstorage.getItem ('xsrf-token'); return req;}"); });

swashbuckle.aspnetcore.annotations

ติดตั้งและเปิดใช้งานคำอธิบายประกอบ

  1. ติดตั้งแพ็คเกจ NUGET ต่อไปนี้ลงในแอปพลิเคชัน ASP.NET Core ของคุณ 

    Package Manager : Install-Package Swashbuckle.AspNetCore.Annotations
CLI : dotnet add package Swashbuckle.AspNetCore.Annotations

  2. ในวิธี ConfigureServices ของ Startup.cs เปิดใช้งานคำอธิบายประกอบภายในในบล็อก config swagger:

     services.addswaggergen (c => {... c.enableannotations ();});

Metadata Operation Operation

เมื่อมีการเปิดใช้งานคำอธิบายประกอบแล้วคุณสามารถเพิ่มประสิทธิภาพการทำงานของข้อมูลเมตาการดำเนินการที่สร้างขึ้นโดยการตกแต่งการกระทำด้วย SwaggerOperationAttribute

 [httppost] [swaggeroperation (summary = "สร้างผลิตภัณฑ์ใหม่", คำอธิบาย = "ต้องการสิทธิ์ผู้ดูแลระบบ", erperationid = "createproduct", แท็ก = new [] {"ซื้อ", "ผลิตภัณฑ์"}) ผลิตภัณฑ์จาก Body] ผลิตภัณฑ์)

metadata การตอบสนองที่ดีขึ้น

ASP.NET CORE จัดเตรียม ProducesResponseTypeAttribute สำหรับการแสดงรายการการตอบสนองที่แตกต่างกันซึ่งสามารถส่งคืนโดยการกระทำ คุณลักษณะเหล่านี้สามารถรวมกับความคิดเห็น XML ตามที่อธิบายไว้ข้างต้นเพื่อรวมคำอธิบายที่เป็นมิตรกับมนุษย์กับการตอบสนองแต่ละครั้งใน swagger ที่สร้างขึ้น หากคุณต้องการทำทั้งหมดนี้ด้วยแอตทริบิวต์เดียวและหลีกเลี่ยงการใช้ความคิดเห็น XML คุณสามารถใช้ SwaggerResponseAttribute S แทน:

 [HTTPPOST] [SwaggerResponse (201, "ผลิตภัณฑ์ถูกสร้างขึ้น", typeof (ผลิตภัณฑ์))] [SwaggerResponse (400, "ข้อมูลผลิตภัณฑ์ไม่ถูกต้อง")] iAtctionResult สาธารณะสร้าง ([frombody] ผลิตภัณฑ์ผลิตภัณฑ์)

เมตาดาต้าพารามิเตอร์เสริม

คุณสามารถใส่คำอธิบายประกอบ "เส้นทาง", "แบบสอบถาม" หรือ "ส่วนหัว" พารามิเตอร์หรือคุณสมบัติที่ถูกผูกไว้ (เช่นตกแต่งด้วย [FromRoute] , [ Parameter [FromQuery] หรือ [FromHeader] ) ด้วย SwaggerParameterAttribute

 [httpget] public iactionresult getProducts ([fromQuery, Swaggerparameter ("คำหลักค้นหา", จำเป็น = true)] คีย์เวิร์ดสตริง)

Enrich Requestbody Metadata

คุณสามารถใส่หมายเหตุประกอบพารามิเตอร์หรือคุณสมบัติที่ถูกผูกไว้ (เช่นตกแต่งด้วย [FromBody] ) ด้วย SwaggerRequestBodyAttribute เพื่อเสริมสร้างข้อมูลเมตา RequestBody ที่สอดคล้องกันที่สร้างขึ้นโดย Swashbuckle:

 [HTTPPOST] สาธารณะ iActionResult createProduct ([frombody, swaggerrequestbody ("payload ผลิตภัณฑ์", จำเป็น = true)] ผลิตภัณฑ์ผลิตภัณฑ์)

Metadata Schema

คุณสามารถใส่คำอธิบายประกอบชั้นเรียนหรือคุณสมบัติด้วย SwaggerSchemaAttribute เพื่อเสริมสร้างเมตา Schema ที่สอดคล้องกันซึ่งสร้างโดย Swashbuckle:

 [Swaggerschema (จำเป็น = ใหม่ [] {"คำอธิบาย"})] ผลิตภัณฑ์ระดับสาธารณะ {[swaggerschema ("ตัวระบุผลิตภัณฑ์", readonly = true)] ID int สาธารณะ {รับ; ชุด; } [Swaggerschema ("คำอธิบายผลิตภัณฑ์")] คำอธิบายสตริงสาธารณะ {รับ; ชุด; } [Swaggerschema ("วันที่ถูกสร้างขึ้น", format = "วันที่")] DateCreated สาธารณะ DateCreated {รับ; ชุด; -

หมายเหตุ: ใน Swagger / OpenAPI วัตถุที่เป็นอนุกรมและคุณสมบัติที่มีอยู่จะแสดงเป็น Schema ซ์สคีมาดังนั้นเหตุใดจึงสามารถนำคำอธิบายประกอบนี้ไปใช้กับทั้งคลาสและคุณสมบัติ นอกจากนี้ยังมีการระบุคุณสมบัติ "ต้องการ" ที่กำหนดไว้เป็นอาร์เรย์ของชื่อทรัพย์สินบนสคีมาระดับบนสุดเมื่อเทียบกับธงในแต่ละคุณสมบัติของแต่ละบุคคล

ใช้ตัวกรองสคีมากับประเภทเฉพาะ

แพ็คเกจ SwaggerGen มีจุดขยายหลายจุดรวมถึงตัวกรองสคีมา (อธิบายไว้ที่นี่) สำหรับการปรับแต่ง schemas ที่สร้างขึ้นทั้งหมด อย่างไรก็ตามอาจมีกรณีที่ควรใช้ตัวกรองกับสคีมาเฉพาะ ตัวอย่างเช่นหากคุณต้องการรวมตัวอย่างสำหรับประเภทเฉพาะใน API ของคุณ สามารถทำได้โดยการตกแต่งประเภทด้วย SwaggerSchemaFilterAttribute :

 // product.cs [swaggerschemafilter (typeof (productschemafilter))] ผลิตภัณฑ์ระดับสาธารณะ {... } // productschemafilter.cspublic คลาส productschemafilter: ischemafilter {โมฆะสาธารณะเปิดใช้งาน ["id"] = ใหม่ openapiinteger (1), ["คำอธิบาย"] = ใหม่ openapistring ("ผลิตภัณฑ์ที่ยอดเยี่ยม")};}}

เพิ่ม Metadata แท็ก

โดยค่าเริ่มต้นเครื่องกำเนิด Swagger จะติดแท็กการดำเนินการทั้งหมดด้วยชื่อคอนโทรลเลอร์ แท็กนี้จะใช้ในการขับเคลื่อนการจัดกลุ่มการดำเนินการใน Swagger-ui หากคุณต้องการให้คำอธิบายสำหรับแต่ละกลุ่มเหล่านี้คุณสามารถทำได้โดยการเพิ่มข้อมูลเมตาสำหรับแต่ละแท็กชื่อคอนโทรลเลอร์ผ่าน SwaggerTagAttribute :

 [Swaggertag ("สร้างอ่านอัปเดตและลบผลิตภัณฑ์")] Public Class ProductsController {... }

หมายเหตุ: สิ่งนี้จะเพิ่มคำอธิบายข้างต้นโดยเฉพาะในแท็กชื่อ "ผลิตภัณฑ์" ดังนั้นคุณควรหลีกเลี่ยงการใช้แอตทริบิวต์นี้หากคุณกำลังติดแท็กการดำเนินการกับสิ่งอื่นนอกเหนือจากชื่อคอนโทรลเลอร์ - เช่นหากคุณกำลังปรับแต่งพฤติกรรมการติดแท็กด้วย TagActionsBy

รายการชนิดย่อยที่รู้จักสำหรับการสืบทอดและ polymorphism

หากคุณต้องการใช้พฤติกรรมการสืบทอดและ/หรือ polymorphism ของ Swashbuckle คุณสามารถใช้คำอธิบายประกอบเพื่อระบุชนิดย่อย "ที่รู้จัก" อย่างชัดเจน สำหรับประเภทฐานที่กำหนด สิ่งนี้จะแทนที่ฟังก์ชั่นตัวเลือกเริ่มต้นซึ่งเลือกชนิดย่อย ทั้งหมด ในแอสเซมบลีเดียวกันกับประเภทฐานดังนั้นจึงต้องเปิดใช้งานอย่างชัดเจนเมื่อคุณเปิดใช้งานคำอธิบายประกอบ:

 // startup.csservices.addswaggergen (c => {c.enableannotations (enableannotationsforinheritance: จริง, enableannotationsforpolymorphism: true);}); // shape.cs [swaggersubtype (typeof (ectangle)] ] รูปทรงคลาสนามธรรมสาธารณะ {}

คลาสพื้นฐาน polymorphic ที่มีเมตาดาต้า discriminator

หากคุณใช้คำอธิบายประกอบเพื่อระบุชนิดย่อย "ที่รู้จัก" อย่างชัดเจน สำหรับประเภทฐาน polymorphic คุณสามารถรวม SwaggerDiscriminatorAttribute เข้ากับ SwaggerSubTypeAttribute เพื่อให้ข้อมูลเมตาเพิ่มเติมเกี่ยวกับคุณสมบัติ "discriminator"

 // startup.csservices.addswaggergen (c => {c.enableannotations (enableannotationsforinheritance: จริง, enableannotationsforpolymorphism: true);}); // shape.cs [swaggerdiscriminator ( = "สี่เหลี่ยมผืนผ้า")] [swaggersubtype (typeof (วงกลม), discriminatorValue = "circle")] รูปแบบนามธรรมสาธารณะสาธารณะ {public shapetype {get; ชุด; -

สิ่งนี้บ่งชี้ว่าเพย์โหลดที่สอดคล้องกันจะมีคุณสมบัติ "shapetype" เพื่อแยกแยะระหว่างชนิดย่อยและคุณสมบัตินั้นจะมีค่าของ "สี่เหลี่ยมผืนผ้า" หากน้ำหนักบรรทุกแสดงถึงประเภท Rectangle และค่าของ "วงกลม" หากเป็นประเภท Circle รายละเอียดนี้จะอธิบายไว้ในนิยามสคีมาที่สร้างขึ้นดังนี้: 

schema: {
  oneOf: [
    {
      $ref: "#/components/schemas/Rectangle"
    },
    {
      $ref: "#/components/schemas/Circle"
    },
  ],
  discriminator: {
    propertyName: shapeType,
    mapping: {
      rectangle: "#/components/schemas/Rectangle",
      circle: "#/components/schemas/Circle",
    }
  }
}

swashbuckle.aspnetcore.cli

ดึง swagger โดยตรงจากชุดประกอบเริ่มต้น

เมื่อแอปพลิเคชันของคุณได้รับการตั้งค่าด้วย swashbuckle (ดูการเริ่มต้นใช้งาน) คุณสามารถใช้เครื่องมือ Swashbuckle CLI เพื่อดึง Swagger / OpenAPI JSON โดยตรงจากชุดประกอบการเริ่มต้นของแอปพลิเคชันของคุณและเขียนลงในไฟล์ สิ่งนี้จะมีประโยชน์หากคุณต้องการรวมการสร้าง swagger ลงในกระบวนการ CI/CD หรือหากคุณต้องการให้บริการจากไฟล์คงที่ในเวลาทำงาน

มันบรรจุเป็นเครื่องมือ. NET ที่สามารถติดตั้งและใช้งานผ่าน Dotnet SDK

เครื่องมือต้องโหลด DLL เริ่มต้นและการพึ่งพาของมันในเวลาทำงาน ดังนั้นคุณควรใช้ dotnet SDK เวอร์ชันที่เข้ากันได้กับแอปพลิเคชันของคุณ ตัวอย่างเช่นหากแอปของคุณตั้งเป้าหมาย net6.0 คุณควรใช้เวอร์ชัน 6.0.xxx ของ SDK เพื่อเรียกใช้เครื่องมือ CLI หากมีเป้าหมาย net8.0 คุณควรใช้เวอร์ชัน 8.0.xxx ของ SDK และอื่น ๆ

ใช้เครื่องมือกับ. NET SDK

  1. ติดตั้งเป็นเครื่องมือระดับโลก 

    dotnet tool install -g Swashbuckle.AspNetCore.Cli

  2. ตรวจสอบว่าเครื่องมือติดตั้งอย่างถูกต้อง 

    swagger tofile --help

  3. สร้างเอกสาร Swagger/ OpenAPI จากชุดประกอบการเริ่มต้นของแอปพลิเคชันของคุณ 

    swagger tofile --output [output] [startupassembly] [swaggerdoc]

    ที่ไหน ...

    • [เอาท์พุท] เป็นเส้นทางสัมพัทธ์ที่ json swagger จะถูกส่งออกไป

    • [StartupAssembly] เป็นเส้นทางที่สัมพันธ์กับแอสเซมบลีเริ่มต้นของแอปพลิเคชันของคุณ

    • [Swaggerdoc] เป็นชื่อของเอกสาร Swagger ที่คุณต้องการเรียกคืนตามที่กำหนดค่าไว้ในคลาสเริ่มต้นของคุณ

ใช้เครื่องมือกับ. NET 6.0 SDK หรือใหม่กว่า

  1. ในรูทโครงการของคุณสร้างไฟล์รายการเครื่องมือ: 

    dotnet new tool-manifest

  2. ติดตั้งเป็นเครื่องมือในท้องถิ่น 

    dotnet tool install Swashbuckle.AspNetCore.Cli

  3. ตรวจสอบว่าเครื่องมือติดตั้งอย่างถูกต้อง 

    dotnet swagger tofile --help

  4. สร้างเอกสาร Swagger / OpenAPI จากชุดประกอบการเริ่มต้นของแอปพลิเคชันของคุณ 

    dotnet swagger tofile --output [output] [startupassembly] [swaggerdoc]

    ที่ไหน ...

    • [เอาท์พุท] เป็นเส้นทางสัมพัทธ์ที่ json swagger จะถูกส่งออกไป

    • [StartupAssembly] เป็นเส้นทางที่สัมพันธ์กับแอสเซมบลีเริ่มต้นของแอปพลิเคชันของคุณ

    • [Swaggerdoc] เป็นชื่อของเอกสาร Swagger ที่คุณต้องการเรียกคืนตามที่กำหนดค่าไว้ในคลาสเริ่มต้นของคุณ

ใช้เครื่องมือ CLI ด้วยการกำหนดค่าโฮสต์ที่กำหนดเอง

เครื่องมือจะดำเนินการในบริบทของโฮสต์เว็บ "เริ่มต้น" อย่างไรก็ตามในบางกรณีคุณอาจต้องการนำสภาพแวดล้อมโฮสต์ของคุณมาเองเช่นหากคุณกำหนดค่าคอนเทนเนอร์ DI แบบกำหนดเองเช่น Autofac สำหรับสถานการณ์นี้เครื่องมือ Swashbuckle CLI จะเปิดเผยเบ็ดที่ใช้การประชุมสำหรับแอปพลิเคชันของคุณ

นั่นคือถ้าแอปพลิเคชันของคุณมีคลาสที่ตรงกับการประชุมการตั้งชื่อดังต่อไปนี้ดังนั้นคลาสนั้นจะถูกใช้เพื่อจัดหาโฮสต์สำหรับเครื่องมือ CLI ที่จะทำงาน

  • public class SwaggerHostFactory ที่มีวิธีการคงที่สาธารณะเรียกว่า CreateHost ด้วยประเภท return IHost

  • public class SwaggerWebHostFactory ที่มีวิธีการคงที่สาธารณะที่เรียกว่า CreateWebHost ด้วยประเภท return IWebHost

ตัวอย่างเช่นคลาสต่อไปนี้สามารถใช้เพื่อใช้ประโยชน์จากการกำหนดค่าโฮสต์เดียวกันกับแอปพลิเคชันของคุณ:

 ระดับสาธารณะ swaggerhostfactory {สาธารณะคงที่ ihost createHost () {return program.createHostBuilder (สตริงใหม่ [0]). build ();}}

swashbuckle.aspnetcore.redoc

เปลี่ยนเส้นทางสัมพัทธ์เป็น UI

โดยค่าเริ่มต้น redoc UI จะถูกเปิดเผยที่ "/api-docs" หากจำเป็นคุณสามารถเปลี่ยนแปลงสิ่งนี้ได้เมื่อเปิดใช้งานมิดเดิลแวร์ใหม่:

 app.useredoc (c => {c.routeprefix = "docs" ... }

เปลี่ยนชื่อเอกสาร

โดยค่าเริ่มต้น REDOC UI จะมีชื่อเอกสารทั่วไป คุณสามารถเปลี่ยนแปลงสิ่งนี้เมื่อเปิดใช้งานมิดเดิลแวร์ใหม่:

 app.useredoc (c => {c.documentTitle = "my api docs"; ... }

ใช้พารามิเตอร์ redoc

จัดส่งเรือใหม่ด้วยชุดพารามิเตอร์การกำหนดค่าทั้งหมดที่อธิบายไว้ที่นี่ https://github.com/rebilly/redoc/blob/main/readme.md#redoc-options-object ใน Swashbuckle สิ่งเหล่านี้ส่วนใหญ่ปรากฏขึ้นผ่านตัวเลือกมิดเดิลแวร์ใหม่:

 app.useredoc (c => {c.specurl ("/v1/swagger.json"); c.enableuntrustedspec (); c.scrollyoffset (10); c.hidehostname (); (200,201 "); sortpropsalphabetically ();});

การใช้ c.SpecUrl("/v1/swagger.json") หลายครั้งภายใน UseReDoc(...) จะไม่เพิ่ม URL หลายรายการ

ฉีด CSS ที่กำหนดเอง

ในการปรับแต่งรูปลักษณ์และความรู้สึกคุณสามารถฉีดสไตล์ CSS เพิ่มเติมได้โดยเพิ่มลงในโฟลเดอร์ wwwroot ของคุณและระบุเส้นทางสัมพัทธ์ในตัวเลือกมิดเดิลแวร์:

 app.useredoc (c => {... c.injectstylesheet ("/redoc/custom.css");}

นอกจากนี้ยังเป็นไปได้ที่จะแก้ไขชุดรูปแบบโดยใช้คุณสมบัติ AdditionalItems ดู https://github.com/rebilly/redoc/blob/main/readme.md#redoc-options-Object สำหรับข้อมูลเพิ่มเติม

 app.useredoc (c => {... c.configobject.additionalItems = ... }

ปรับแต่ง index.html

ในการปรับแต่ง UI นอกเหนือจากตัวเลือกพื้นฐานที่ระบุไว้ข้างต้นคุณสามารถจัดเตรียมหน้า redoc index.html เวอร์ชันของคุณเอง:

 app.useredoc (c => {c.indexstream = () => getType (). แอสเซมบลี. getManifestresourceStream ("customIndex.redoc.index.html"); // ต้องการไฟล์ที่จะเพิ่มเป็นทรัพยากรที่ฝังอยู่});

ในการเริ่มต้นใช้งานคุณควรยึด index.html ที่กำหนดเองของคุณในเวอร์ชันเริ่มต้น

ขยาย
ข้อมูลเพิ่มเติม
แอปที่เกี่ยวข้อง
แนะนำสำหรับคุณ
ข้อมูลที่เกี่ยวข้อง ทั้งหมด