利用Swashbuckle生成Web API Help Pages

本文将通过Swagger的.NET Core的实现封装工具Swashbuckle来生成上一篇-《创建ASP.NET Core Web API》的帮助文档。

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

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

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

定制&扩展

API描述信息

ConfigureSwaggerGen方法可以用来添加作者、版权、描述等信息。

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

XML注释

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

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

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

个人博客

我的个人博客

利用Swashbuckle生成Web API Help Pages的更多相关文章

  1. 利用Swashbuckle生成Web API Help Pages

    利用Swashbuckle生成Web API Help Pages 这系列文章是参考了.NET Core文档和源码,可能有人要问,直接看官方的英文文档不就可以了吗,为什么还要写这些文章呢? 原因如下: ...

  2. Loadrunner 脚本开发-利用Loadrunner生成Web service测试脚本

    脚本开发-利用Loadrunner生成Web service测试脚本 1.选择协议--Web Service,如下图 2.导入服务 入口1:点击Manage Services ->弹出窗中选择“ ...

  3. ASP.NET Web API Help Pages using Swagger

    Understanding the various methods of an API can be a challenge for a developer when building a consu ...

  4. web API help pages with Swagger / OpenAPI

    https://docs.microsoft.com/en-us/aspnet/core/tutorials/web-api-help-pages-using-swagger?view=aspnetc ...

  5. 使用ASP.NET Web API Help Pages 创建在线接口文档

    操作步骤 1.新建Web API项目 2.在项目Areas文件夹下找到以下文件,取消注释图中代码. 3.右键解决方案,属性,如图设置. 4.运行程序,点击右上角API 接口列表: 详情-无参数: 详情 ...

  6. Swagger+AutoRest 生成web api客户端(.Net)

    简介 对于.net来说,用web api来构建服务是一个不错的选择,都是http请求,调用简单,但是如果真的要在程序中调用,则还有些工作要做,比如我们需要手写httpClient调用,并映射Model ...

  7. 【ASP.NET Web API2】利用HttpClient调用Web API(TODO)

    参照: 在一个空ASP.NET Web项目上创建一个ASP.NET Web API 2.0应用 纯属记录一下遇到的问题: 我们利用HttpClient来调用自宿主方式寄宿的Web API.HttpCl ...

  8. 利用DelegatingHandler实现Web Api 的Api key校验

    客户端在请求Web Api时可以有以下两种方式提供API key 基于Querystring提供Api key http://localhost:57967/Api/Values?key=12345 ...

  9. 自动生成web api接口文档

    然后打开web程序,访问ip:port/Help. 为什么可以直接输入Help就能访问呢,因为这个插件本身已经配置了路径,如下. public class HelpPageAreaRegistrati ...

随机推荐

  1. python 基础 ----- 常用的方法

    one.将英文字符设置大小写 upper()  :将英文字符设置大写 lower()   :将英文字符设置小写 two.去掉字符串的首尾空格    不能去除字符串中间的空格偶 strip() : 去掉 ...

  2. php下kafka实践

    Kafka是一种高吞吐的分布式发布订阅消息系统 kafka安装和简单测试 安装kafka 下载 wget https://www-us.apache.org/dist/kafka/2.1.1/kafk ...

  3. Python-yield生成器

    1.引入生成器的目的: 通常的for...in...循环中,in后面是一个数组,这个数组就是一个可迭代对象,类似的还有链表,字符串,文件.它可以是mylist = [1, 2, 3],也可以是myli ...

  4. ASP.NET Core下发布网站图解

    与ASP.NET时代不同,ASP.NET Core不再是由IIS工作进程(w3wp.exe)托管,而是使用自托管Web服务器(Kestrel)运行,IIS则是作为反向代理的角色转发请求到Kestrel ...

  5. vue-cli 2.x脚手架build目录中的webpack.base.conf.js配置文件

    此文章用来解释vue-cli脚手架build目录中的webpack.base.conf.js配置文件,适用于vue-cli 2.x版本 此配置文件是vue开发环境的wepack相关配置文件,主要用来处 ...

  6. nginx 添加response响应头

    硬添

  7. linux一台服务器配置多个Tomcat

    前提:linux服务器上已经运行多个Tomcat,再去搭建一个Tomcat服务 1.官网下载Tomcat 2.上传到服务器指定一个目录/usr/local/tomcat 3.然后解压tar包,tar ...

  8. shell速查

    Shell是一种脚本语言,那么,就必须有解释器来执行这些脚本,常见的脚本解释器有: bash:是Linux标准默认的shell.bash由Brian Fox和Chet Ramey共同完成,是Bourn ...

  9. 设计模式学习心得<桥接模式 Bridge>

    说真的在此之前,几乎没有对于桥接模式的应用场景概念. 桥接(Bridge)是用于把抽象化与实现化解耦,使得二者可以独立变化.这种类型的设计模式属于结构型模式,它通过提供抽象化和实现化之间的桥接结构,来 ...

  10. amazeui分页

    <link rel="stylesheet" href="../../static/css/manage/amazeui.min.css" /> & ...