利用Swashbuckle生成WebAPIHelpPages

Swashbuckle简介

Swashbuckle有两个核心组件：

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

在middleware中添加并配置Swagger

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

 
 
 
 
    
  
  
  
  
  1. "Swashbuckle": "6.0.0-beta902" 
    2.

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

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

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

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

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

定制&扩展

API描述信息

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

XML注释

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

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

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

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

名称栏目：利用Swashbuckle生成WebAPIHelpPages
文章URL：http://www.csdahua.cn/qtweb/news4/392604.html

网站建设、网络推广公司-快上网，是专注品牌与效果的网站制作，网络营销seo公司；服务项目有等

广告

声明：本网站发布的内容（图片、视频和文字）以用户投稿、用户转载内容为主，如果涉及侵权请尽快告知，我们将会在第一时间删除。文章观点不代表本网站立场，如需处理请联系客服。电话：028-86922220；邮箱：631063699@qq.com。内容未经允许不得转载，或转载时需注明来源： 快上网

成都快上网为您推荐相关内容

品牌网站制作知识

分类信息网

响应式网站　　 　成都商城app开发　　 　广汉锦华建材　　 　成都logo设计公司　　 　重庆小程序开发公司　　 　重庆托管服务器　　 　四川成都做网站　　 　简阳威斯达宇　　 　网站seo优化　　 　成都光华机房　　 　gyruijie.cn　　 　达州网站建设　　 　网站建设报价方案　　 　新型地坪材料　　 　bgp多线机房托管　　 　腾讯云虚拟主机　　 　大橙子建站　　 　重庆电信回兴机房　　 　网络推广公司　　 　模板商城网站