利用Swashbuckle生成Web API Help Pages

最新推荐文章于 2022-04-06 00:08:36 发布
最新推荐文章于 2022-04-06 00:08:36 发布
阅读量880 收藏
点赞数 1
文章标签： web api mac net-core help-pages Swagger
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/CharlieThinker/article/details/53214438
版权

利用Swashbuckle生成Web API Help Pages

这系列文章是参考了.NET Core文档和源码，可能有人要问，直接看官方的英文文档不就可以了吗，为什么还要写这些文章呢？

原因如下：

  • 官方文档涉及的内容相当全面，属于那种大而全的知识仓库，不太适合初学者，很容易让人失去重要，让人掉入到具体的细节之中。
  • 对于大多数人来讲开发语言只是工具，程序员都有一个通病，就是死磕工具，把工具学深。我认为在工具上没有必要投入太多时间，以能高效地完成日常的工作项目为准即可。要需求驱动学习，你需要什么学什么。如果你学的新技术新特性只是屠龙之技或者只需要用到的时候去查一下即可的话，这种死磕这又有什么用。没有必要花120%的时间去学100%的知识，你只需要花20%的时间去学习80%的知识就可以了，剩下的等实际的项目中用到的时候去查就可以了,工具只是工具，不是工作本身。
  • 目前基本所有的文章都是基于Windows平台的Visual Studio IDE来介绍的。而我用的是一台Mac，所以我将基于Mac平台的Visual Studio Code讲解适合我们实际项目中遇到的知识。
  • 还有一点，就是这是我个人的学习总结。

这系列文章就是让你去花20%的时间去学80%的东西，剩下的20%再去看官方文档。

本文将通过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：

"Swashbuckle": "6.0.0-beta902"

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

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

{
  "swagger": "2.0",
  "info": {
    "version": "v1",
    "title": "API V1"
  },
  "basePath": "/",
  "paths": {
    "/api/User": {
      "get": {
        "tags": [
          "User"
        ],
        "operationId": "ApiUserGet",
        "consumes": [],
        "produces": [
          "text/plain",
          "application/json",
          "text/json"
        ],
        "responses": {
          "200": { "description": "Success", "schema": { "type": "array", "items": { "$ref": "#/definitions/UserItem" } } } },
        "deprecated": false
      },
      "post": {
        "tags": [
          "User"
        ],
        "operationId": "ApiUserPost",
        "consumes": [
          "application/json",
          "text/json",
          "application/json-patch+json"
        ],
        "produces": [],
        "parameters": [
          {
            "name": "item",
            "in": "body",
            "required": false,
            "schema": { "$ref": "#/definitions/UserItem" } }
        ],
        "responses": {
          "200": { "description": "Success" } },
        "deprecated": false
      }
    },
    "/api/User/{id}": {
      "get": {
        "tags": [
          "User"
        ],
        "operationId": "ApiUserByIdGet",
        "consumes": [],
        "produces": [],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "type": "string" }
        ],
        "responses": {
          "200": { "description": "Success" } },
        "deprecated": false
      },
      "put": {
        "tags": [
          "User"
        ],
        "operationId": "ApiUserByIdPut",
        "consumes": [
          "application/json",
          "text/json",
          "application/json-patch+json"
        ],
        "produces": [],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "type": "string" },
          {
            "name": "item",
            "in": "body",
            "required": false,
            "schema": { "$ref": "#/definitions/UserItem" } }
        ],
        "responses": {
          "200": { "description": "Success" } },
        "deprecated": false
      },
      "delete": {
        "tags": [
          "User"
        ],
        "operationId": "ApiUserByIdDelete",
        "consumes": [],
        "produces": [],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "type": "string" }
        ],
        "responses": {
          "200": { "description": "Success" } },
        "deprecated": false
      },
      "patch": {
        "tags": [
          "User"
        ],
        "operationId": "ApiUserByIdPatch",
        "consumes": [
          "application/json",
          "text/json",
          "application/json-patch+json"
        ],
        "produces": [],
        "parameters": [
          {
            "name": "item",
            "in": "body",
            "required": false,
            "schema": { "$ref": "#/definitions/UserItem" } },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "type": "string" }
        ],
        "responses": {
          "200": { "description": "Success" } },
        "deprecated": false
      }
    },
    "/api/Values": {
      "get": {
        "tags": [
          "Values"
        ],
        "operationId": "ApiValuesGet",
        "consumes": [],
        "produces": [
          "text/plain",
          "application/json",
          "text/json"
        ],
        "responses": {
          "200": { "description": "Success", "schema": { "type": "array", "items": { "type": "string" } } } },
        "deprecated": false
      },
      "post": {
        "tags": [
          "Values"
        ],
        "operationId": "ApiValuesPost",
        "consumes": [
          "application/json",
          "text/json",
          "application/json-patch+json"
        ],
        "produces": [],
        "parameters": [
          {
            "name": "value",
            "in": "body",
            "required": false,
            "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Success" } },
        "deprecated": false
      }
    },
    "/api/Values/{id}": {
      "get": {
        "tags": [
          "Values"
        ],
        "operationId": "ApiValuesByIdGet",
        "consumes": [],
        "produces": [
          "text/plain",
          "application/json",
          "text/json"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "type": "integer",
            "format": "int32" }
        ],
        "responses": {
          "200": { "description": "Success", "schema": { "type": "string" } } },
        "deprecated": false
      },
      "put": {
        "tags": [
          "Values"
        ],
        "operationId": "ApiValuesByIdPut",
        "consumes": [
          "application/json",
          "text/json",
          "application/json-patch+json"
        ],
        "produces": [],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "type": "integer",
            "format": "int32" },
          {
            "name": "value",
            "in": "body",
            "required": false,
            "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Success" } },
        "deprecated": false
      },
      "delete": {
        "tags": [
          "Values"
        ],
        "operationId": "ApiValuesByIdDelete",
        "consumes": [],
        "produces": [],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "type": "integer",
            "format": "int32" }
        ],
        "responses": {
          "200": { "description": "Success" } },
        "deprecated": false
      }
    }
  },
  "definitions": {
    "UserItem": {
      "type": "object",
      "properties": {
        "key": {
          "type": "string" },
        "name": {
          "type": "string" },
        "age": {
          "format": "int32",
          "type": "integer" }
      }
    }
  },
  "securityDefinitions": {}
}

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

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

定制&扩展

API描述信息

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

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

XML注释

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

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

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

个人博客

我的个人博客

CharlieThinker
关注
  • 1
    点赞
  • 踩
  • 0
    收藏
    觉得还不错? 一键收藏
  • 0
    评论
Solidworks API Help CN.xlsx
02-19
solidworks api帮助文件 翻译目录，示例如下： Access Edges on Rip Feature Example (C#) 此示例显示如何访问接缝特征上的边。 Access Selections Example (VBA) - Code 此示例将基挤出的长度加倍。暗交换为...
在.net core 2中使用Swashbuckle (Swagger)
Freewind的专栏
07-23 4357
注：如果在WebApi中使用了非REST api的Action，需要在Action上添加[Route("actionname")]属性 或者在controller统一处理[Route("api/[controller]/[action]")]。   查看或下载示例代码（如何下载） Swashbuckle 有三个主要组成部分： Swashbuckle.AspNetCore.Swagge...
Asp.Net Core遇到Swagger(二)-Swashbuckle技巧a篇
关关长语
08-21 1829
当Asp.Net Core遇到Swagger，使用Swashbuckle的基础知识和实践技巧总结a篇。
Asp.Net Core遇到Swagger(四)-Swashbuckle技巧c篇
关关长语
08-26 2399
接Swashbuckle技巧c篇，与Action相关的配置和操作，此处为c篇内容。
Swagger简易教程——Swashbuckle版
lxf310的专栏
10-11 1621
Swagger 是一个可用于生成、描述、调用和可视化 RESTful 风格的 Web 服务的规范和框架。本文将介绍如何使用Swashbuckle为你的Web API应用程序添加Swagger说明文档。 目录 准备 实用配置 1. 利用XML备注生成说明文档 2. 利用Swagger属性标签进一步丰富文档 3. 为从Request中直接获取的输入添加文档 4. 自定义Swagger的文档路径 准备 本文的示例代码使用了.NET Framework 4.6.1。首先，创建一个新的Web API
Swashbuckle一个webapi调试利器
xyx_0300的博客
08-31 276
直接导入一个包： Install-Package Swashbuckle 然后F5启动项目 输入 地址：你的地址/swagger 运行以后，发现我报错了 发生上述错误，请在，SwaggerNet类中，注释类上面的两行，就会运行成功 这时，运行成功 安装完成后，写注释并没有在swagger页面上面增加，所以我们现在开开启注释 在SwaggerConfig类中，EnableSwagger的时候添加下面XML解析 c.IncludeXmlComments(GetXmlCommentsPath()); .
ASP.NET Web API如何将注释自动生成帮助文档
01-02
ASP.NET Web API从注释生成帮助文档 默认情况下，ASP.NET Web API不从Controller的注释中生成帮助文档。如果要将注释作为Web API帮助文档的一部分，比如在帮助文档的Description栏目中显示方法注释中的summary，需要...
SOLIDWORKS 2019 API Help.zip
03-04
SolidWorks 2019 API 离线文档chm格式文件。...<1>SOLIDWORKS API Help.chm <2>SOLIDWORKS PDM Professional API Help .chm <3>SOLIDWORKS Type Library .chm <4>SolidWorks.Interop.sldworks Namespace.chm
JDKAPI.rar_Help!_jdkapi
最新发布
09-21
《JDKAPI.rar_Help!_jdkapi》这个压缩包文件是Java开发者的重要参考资料，它包含了一份详尽的JDK API中文文档，旨在...因此，无论你是Java的新手还是专家，都应该充分利用这份JDK API中文文档，提升自己的编程技能。
dotnet-webapi-template：一个dotnet核心无控制器Web api解决方案模板，可帮助您入门
02-26
要查看所有可用的模板选项，请运行： dotnet new webapi-bizapp --help布局解决方案的布局由命令/查询分离驱动，同时隔离了域层域层服务集合的类/服务没有依赖关系应用层类/服务以命令/查询方式为域提供服务依赖项...
Swashbuckle, 无缝地向WebApi项目添加一个 swagger ！.zip
09-18
Swashbuckle, 无缝地向WebApi项目添加一个 swagger ！
Swashbuckle源码应用之最后一次修改Swagger中OpenApi.json机会
关关长语
04-06 1170
讲解Swashbuckle中对swagger的文档数据openapi.json的自定义配置。
我的Swagger实例ASP.NET MVC 集成SwaggerUI ，Swashbuckle v5.6.0配置, api描述
橙-极纪元-cplvfx-JJY.Cheng
09-21 680
ASP.NET MVC集成SwaggerUI，Swashbuckle v5.6.0配置 https://blog.csdn.net/cplvfx/article/details/108705513 注意： 1.在此之前你要确定你已经通过NuGet安装好Swashbuckle v5.6.0 2.Web项目右键属性-》生成-》勾选XML文档文件，建议用默认路径 3.并且，修改了 ，项目》App_Start》SwaggerConfig.cs 104 行 取消c.Include...
C# Swagger 生成API接口说明文档
大新软件老杨
03-21 2973
后端完成了接口之后，肯定需要告诉前端，不管是整理成 txt/excel/markdown 文档，亦或是写完一个接口就直接发微信告诉前端，总是要多做一步的事情，而 Swagger 则可以帮我们省去这一步。通过配置之后，Swagger 就可以根据我们的接口自动生成 API 的接口文档 　　Swagger 是一个可以将接口文档自动生成，同时可以对接口功能进行测试的开源框架，在 ASP.NET Core 环境下，主流的有 Swashbuckle.AspNetCore 和 NSwag 这两个开源框架帮助我们生成 S
ASP.NET Core Swagger的使用(Swashbuckle工具版)
专注WMS和日化制药行业MES的研发
07-04 258
1、首先安装工具包 vs2019为例： 工具>NUGet包管理器>程序包管理器控制台， 输入以下命令： Install-Package Swashbuckle.AspNetCore 2、安装好后，Startup.cs下注册服务，代码段如下： 添加了 services.AddSwaggerGen(m => { m.SwaggerDoc(“v1”, new OpenApiInfo { Title = “TodoApi”, Version = “v1” }); }); 这段代码， TodoApi
swashbuckle (swagger 插件 java .net 中都有使用)
Cassandra_sj的博客
02-23 556
紧接着上一篇博客网址如下 https://blog.csdn.net/Cassandra_sj/article/details/87472722 我们这里使用的API没有界面，我们需要的是GUI 那么首先我们需要做的是打开项目右键点击依赖(dependencies)–&amp;gt;管理NuGet包 --&amp;gt;broswer search --&amp;gt; swashbuckle.aspnetcore ...
.NetCore——WebApi_Swagger(Swashbuckle.AspNetCore)配置
qiaofan_乔凡的博客
11-25 1383
.NetCore——WebApi_Swagger(Swashbuckle.AspNetCore)配置 一、Swagger安装 在NuGet中安装Swashbuckle.AspNetCore 二、配置 在Startup.ConfigureServices方法中，注册所需的Swagger //注册Swagger services.AddSwaggerGen(c => ...
swagger返回参数的注释
热门推荐
爱生活爱敏敏的博客
01-20 1万+
.net core3.0 webapi 首先安装包Swashbuckle.AspNetCore.Annotations 然后在Startup配置swagger地方加上一句代码 i.EnableAnnotations();//注释 使用的话在控制器的方法中加上 [SwaggerResponse(0,"文档注释",typeof(Product))] 注意这个typeof的参数就是你要返回的...
使用 Swagger UI 与 Swashbuckle 创建 RESTful Web API 帮助文件
weixin_33698823的博客
04-14 195
作者：Sreekanth Mothukuru 2016年2月18日 本文旨在介绍如何使用常用的 Swagger 和 Swashbuckle 框架创建描述 Restful API 的交互界面，并为 API 用户提供丰富的探索、文件和操作体验。 源代码: 下载 SwaggerUi_2.zip 步骤 在本文中，我们将在 Asp.Net 创建一个简单的 Res...

“相关推荐”对你有帮助么？

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值