利用Swashbuckle生成Web API Help Pages

开发 开发工具
Swashbuckle有两个核心组件:Swashbuckle.SwaggerGen: 提供生成描述对象,方法,返回类型等JSON Swagger文档的功能。Swashbuckle.SwaggerUI: 一个Swagger UI工具的嵌入式版本,可以使用上面的文档来创建可定制化的Web API的功能描述,包含内置的公共方法的测试工具。

[[189063]]

Swashbuckle简介

Swashbuckle有两个核心组件:

  • Swashbuckle.SwaggerGen: 提供生成描述对象,方法,返回类型等JSON Swagger文档的功能。
  • Swashbuckle.SwaggerUI: 一个Swagger UI工具的嵌入式版本,可以使用上面的文档来创建可定制化的Web API的功能描述,包含内置的公共方法的测试工具。

在middleware中添加并配置Swagger

首先,要将Swashbuckle添加到项目中的project.json:

  1. "Swashbuckle""6.0.0-beta902" 

然后在Configure方法中添加SwaggerGen到services集合中,接着在ConfigureServices方法中,允许中间件(middleware)为生成的JSON文档和SwaggerUI提供服务。

执行dotnet run命令,并导航到http://localhost:5000/swagger/v1/swagger.json 查看描述终结点的文档。

  1. 在middleware中添加并配置Swagger 
  2. 首先,要将Swashbuckle添加到项目中的project.json: 
  3.  
  4. "Swashbuckle""6.0.0-beta902" 
  5. 然后在Configure方法中添加SwaggerGen到services集合中,接着在ConfigureServices方法中,允许中间件(middleware)为生成的JSON文档和SwaggerUI提供服务。 
  6.  
  7.  
  8.  
  9. 执行dotnet run命令,并导航到http://localhost:5000/swagger/v1/swagger.json 查看描述终结点的文档。 
  10.  
  11.   "swagger""2.0"
  12.   "info": { 
  13.     "version""v1"
  14.     "title""API V1" 
  15.   }, 
  16.   "basePath""/"
  17.   "paths": { 
  18.     "/api/User": { 
  19.       "get": { 
  20.         "tags": [ 
  21.           "User" 
  22.         ], 
  23.         "operationId""ApiUserGet"
  24.         "consumes": [], 
  25.         "produces": [ 
  26.           "text/plain"
  27.           "application/json"
  28.           "text/json" 
  29.         ], 
  30.         "responses": { 
  31.           "200": { 
  32.             "description""Success"
  33.             "schema": { 
  34.               "type""array"
  35.               "items": { 
  36.                 "$ref""#/definitions/UserItem" 
  37.               } 
  38.             } 
  39.           } 
  40.         }, 
  41.         "deprecated"false 
  42.       }, 
  43.       "post": { 
  44.         "tags": [ 
  45.           "User" 
  46.         ], 
  47.         "operationId""ApiUserPost"
  48.         "consumes": [ 
  49.           "application/json"
  50.           "text/json"
  51.           "application/json-patch+json" 
  52.         ], 
  53.         "produces": [], 
  54.         "parameters": [ 
  55.           { 
  56.             "name""item"
  57.             "in""body"
  58.             "required"false
  59.             "schema": { 
  60.               "$ref""#/definitions/UserItem" 
  61.             } 
  62.           } 
  63.         ], 
  64.         "responses": { 
  65.           "200": { 
  66.             "description""Success" 
  67.           } 
  68.         }, 
  69.         "deprecated"false 
  70.       } 
  71.     }, 
  72.     "/api/User/{id}": { 
  73.       "get": { 
  74.         "tags": [ 
  75.           "User" 
  76.         ], 
  77.         "operationId""ApiUserByIdGet"
  78.         "consumes": [], 
  79.         "produces": [], 
  80.         "parameters": [ 
  81.           { 
  82.             "name""id"
  83.             "in""path"
  84.             "required"true
  85.             "type""string" 
  86.           } 
  87.         ], 
  88.         "responses": { 
  89.           "200": { 
  90.             "description""Success" 
  91.           } 
  92.         }, 
  93.         "deprecated"false 
  94.       }, 
  95.       "put": { 
  96.         "tags": [ 
  97.           "User" 
  98.         ], 
  99.         "operationId""ApiUserByIdPut"
  100.         "consumes": [ 
  101.           "application/json"
  102.           "text/json"
  103.           "application/json-patch+json" 
  104.         ], 
  105.         "produces": [], 
  106.         "parameters": [ 
  107.           { 
  108.             "name""id"
  109.             "in""path"
  110.             "required"true
  111.             "type""string" 
  112.           }, 
  113.           { 
  114.             "name""item"
  115.             "in""body"
  116.             "required"false
  117.             "schema": { 
  118.               "$ref""#/definitions/UserItem" 
  119.             } 
  120.           } 
  121.         ], 
  122.         "responses": { 
  123.           "200": { 
  124.             "description""Success" 
  125.           } 
  126.         }, 
  127.         "deprecated"false 
  128.       }, 
  129.       "delete": { 
  130.         "tags": [ 
  131.           "User" 
  132.         ], 
  133.         "operationId""ApiUserByIdDelete"
  134.         "consumes": [], 
  135.         "produces": [], 
  136.         "parameters": [ 
  137.           { 
  138.             "name""id"
  139.             "in""path"
  140.             "required"true
  141.             "type""string" 
  142.           } 
  143.         ], 
  144.         "responses": { 
  145.           "200": { 
  146.             "description""Success" 
  147.           } 
  148.         }, 
  149.         "deprecated"false 
  150.       }, 
  151.       "patch": { 
  152.         "tags": [ 
  153.           "User" 
  154.         ], 
  155.         "operationId""ApiUserByIdPatch"
  156.         "consumes": [ 
  157.           "application/json"
  158.           "text/json"
  159.           "application/json-patch+json" 
  160.         ], 
  161.         "produces": [], 
  162.         "parameters": [ 
  163.           { 
  164.             "name""item"
  165.             "in""body"
  166.             "required"false
  167.             "schema": { 
  168.               "$ref""#/definitions/UserItem" 
  169.             } 
  170.           }, 
  171.           { 
  172.             "name""id"
  173.             "in""path"
  174.             "required"true
  175.             "type""string" 
  176.           } 
  177.         ], 
  178.         "responses": { 
  179.           "200": { 
  180.             "description""Success" 
  181.           } 
  182.         }, 
  183.         "deprecated"false 
  184.       } 
  185.     }, 
  186.     "/api/Values": { 
  187.       "get": { 
  188.         "tags": [ 
  189.           "Values" 
  190.         ], 
  191.         "operationId""ApiValuesGet"
  192.         "consumes": [], 
  193.         "produces": [ 
  194.           "text/plain"
  195.           "application/json"
  196.           "text/json" 
  197.         ], 
  198.         "responses": { 
  199.           "200": { 
  200.             "description""Success"
  201.             "schema": { 
  202.               "type""array"
  203.               "items": { 
  204.                 "type""string" 
  205.               } 
  206.             } 
  207.           } 
  208.         }, 
  209.         "deprecated"false 
  210.       }, 
  211.       "post": { 
  212.         "tags": [ 
  213.           "Values" 
  214.         ], 
  215.         "operationId""ApiValuesPost"
  216.         "consumes": [ 
  217.           "application/json"
  218.           "text/json"
  219.           "application/json-patch+json" 
  220.         ], 
  221.         "produces": [], 
  222.         "parameters": [ 
  223.           { 
  224.             "name""value"
  225.             "in""body"
  226.             "required"false
  227.             "schema": { 
  228.               "type""string" 
  229.             } 
  230.           } 
  231.         ], 
  232.         "responses": { 
  233.           "200": { 
  234.             "description""Success" 
  235.           } 
  236.         }, 
  237.         "deprecated"false 
  238.       } 
  239.     }, 
  240.     "/api/Values/{id}": { 
  241.       "get": { 
  242.         "tags": [ 
  243.           "Values" 
  244.         ], 
  245.         "operationId""ApiValuesByIdGet"
  246.         "consumes": [], 
  247.         "produces": [ 
  248.           "text/plain"
  249.           "application/json"
  250.           "text/json" 
  251.         ], 
  252.         "parameters": [ 
  253.           { 
  254.             "name""id"
  255.             "in""path"
  256.             "required"true
  257.             "type""integer"
  258.             "format""int32" 
  259.           } 
  260.         ], 
  261.         "responses": { 
  262.           "200": { 
  263.             "description""Success"
  264.             "schema": { 
  265.               "type""string" 
  266.             } 
  267.           } 
  268.         }, 
  269.         "deprecated"false 
  270.       }, 
  271.       "put": { 
  272.         "tags": [ 
  273.           "Values" 
  274.         ], 
  275.         "operationId""ApiValuesByIdPut"
  276.         "consumes": [ 
  277.           "application/json"
  278.           "text/json"
  279.           "application/json-patch+json" 
  280.         ], 
  281.         "produces": [], 
  282.         "parameters": [ 
  283.           { 
  284.             "name""id"
  285.             "in""path"
  286.             "required"true
  287.             "type""integer"
  288.             "format""int32" 
  289.           }, 
  290.           { 
  291.             "name""value"
  292.             "in""body"
  293.             "required"false
  294.             "schema": { 
  295.               "type""string" 
  296.             } 
  297.           } 
  298.         ], 
  299.         "responses": { 
  300.           "200": { 
  301.             "description""Success" 
  302.           } 
  303.         }, 
  304.         "deprecated"false 
  305.       }, 
  306.       "delete": { 
  307.         "tags": [ 
  308.           "Values" 
  309.         ], 
  310.         "operationId""ApiValuesByIdDelete"
  311.         "consumes": [], 
  312.         "produces": [], 
  313.         "parameters": [ 
  314.           { 
  315.             "name""id"
  316.             "in""path"
  317.             "required"true
  318.             "type""integer"
  319.             "format""int32" 
  320.           } 
  321.         ], 
  322.         "responses": { 
  323.           "200": { 
  324.             "description""Success" 
  325.           } 
  326.         }, 
  327.         "deprecated"false 
  328.       } 
  329.     } 
  330.   }, 
  331.   "definitions": { 
  332.     "UserItem": { 
  333.       "type""object"
  334.       "properties": { 
  335.         "key": { 
  336.           "type""string" 
  337.         }, 
  338.         "name": { 
  339.           "type""string" 
  340.         }, 
  341.         "age": { 
  342.           "format""int32"
  343.           "type""integer" 
  344.         } 
  345.       } 
  346.     } 
  347.   }, 
  348.   "securityDefinitions": {} 

该文档用来驱动Swagger UI,可以导航http://localhost:5000/swagger/ui来查看Swagger UI。

 

在UserController里面的每个方法都可以在该页面上通过点击”Try it out!”进行测试。

定制&扩展

API描述信息

  1. services.ConfigureSwaggerGen(options => 
  2.     options.SingleApiVersion(new Info 
  3.     { 
  4.         Version = "v1"
  5.         Title = "User Web API"
  6.         Description = "ASP.NET Core Web API"
  7.         TermsOfService = "None"
  8.         Contact = new Contact { Name = "Charlie Chu", Email = "charlie.thinker@aliyun.com", Url = "http://zhuchenglin.me/" }, 
  9.         License = new License { Name = "The MIT License", Url = "http://zhuchenglin.me/" } 
  10.     }); 
  11. }); 

XML注释

通过在project.json添加“xmlDoc”: true来启用XML注释。

ApplicationBasePath获取该应用的根路径,它必须为XML注释设置一个完整的路径,生成的XML注释名称基于你的应用程序的名称。

注意这个界面是通过之前生成的JSON文件来驱动的,所有的这些API描述信息和XML注释都会写入到这个文件中。

【本文为51CTO专栏作者“朱成林”的原创稿件,转载请联系原作者】

戳这里,看该作者更多好文

责任编辑:武晓燕 来源: 51CTO专栏
相关推荐

2011-04-15 09:20:56

ASP.NET MVC

2011-12-23 09:28:31

Java

2009-04-13 11:38:27

IBMdWWeb

2023-07-26 17:13:38

2009-06-15 15:43:54

Stripes实现Ja

2016-10-18 10:23:14

Docker容器SSL证书

2020-11-04 13:18:34

WebAPIWeb Share A

2011-10-27 16:24:48

API

2011-09-16 14:21:47

Web API

2014-08-12 10:28:08

AngularJS外部API

2012-04-25 11:21:41

Visual Stud

2019-11-13 11:52:46

区块链API比特币

2009-06-23 16:52:16

JSFHibernateWeb应用

2010-09-15 12:15:23

NessusWEB应用安全扫描

2017-02-14 21:15:48

2011-01-20 10:17:25

ibmdwWeb

2012-06-20 14:34:03

jQuery

2017-08-09 15:57:11

JavaScriptHtml5音频

2010-08-09 08:48:46

File APIWeb

2009-07-03 09:12:59

Java JSP
点赞
收藏

51CTO技术栈公众号