# 使用Swashbuckle为Asp.net API生成文档

整理 By HeTJ@2020.11.11

序言

• 开发REST API有一个重要的任务就是生成API的文档

• 可以使用Swashbuckle、NSwag

工具

Visual Studio Community 2019

方法与步骤

• 创建一个ASP.NET Web Application (.NET Framework 4.5)项目；

  (Web API)

• 通过Nuget Package Manager Console添加API所需的引用；

  Install-Package Microsoft.AspNet.WebApi

  

  packages.config修改完成。

• [Global.asax]增加一个全局引用类。

在 Application_Start 中加入：

GlobalConfiguration.Configuration.Routes.MapHttpRoute("Default", 

    "{controller}/{id}", 

    new { id = RouteParameter.Optional });

如下图

• 为项目增加一个文件夹Controllers（如果不存在），然后增加一个类VersionController, 写入以下代码：

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.Http;

namespace JwtWebApi.Controllers
{
    public class VersionController : ApiController
    {
        public IHttpActionResult Get() {
            return Ok("Web API V1.0");
        }
    }
}

• 运行

• 通过Swashbuckle生成文档

  通过Nuget Package Manage Console安装Swashbuckle：

Install-Package Swashbuckle -Version 5.3.2

如图示

安装完成

• 运行，http://localhost:60304/swagger可以看到api文档。

注意：60304是随机端口，可通过查看项目属性(Alt+Enter)-Web找到。

• 再次运行，出现错误

  

  解决冲突办法： 第一步：找到SwaggerConfig.cs页面，引用：using System.Linq; 第二步:找到大概168行的代码，是注释状态，取消注释。再执行可以解决。

  c.ResolveConflictingActions(apiDescriptions => apiDescriptions.First());

• 运行，输入地址：localhost:60304/swagger，回车

  

  查看api

  

  OK。点击Show/Hide

  

• 测试/Acount/ValidLogin接口

  账号密码不一样（演示非法用户登录）

  

  账号密码一样（演示合法用户登录成功）

  

• 完成。

See also:

ASP.NET Core web API documentation with Swagger / OpenAPI

Get started with Swashbuckle and ASP.NET Core