Swagger UI教程 API 文档神器 搭配Node使用 web api 接口文档 mvc接口文档

Posted ycmail

tags:

篇首语：本文由小常识网(cha138.com)小编为大家整理，主要介绍了Swagger UI教程 API 文档神器 搭配Node使用 web api 接口文档 mvc接口文档相关的知识，希望对你有一定的参考价值。

两种方案

一、Swagger 配置 web Api 接口文档美化

二、通过NodeJS 发布Swagger UI 配置api 文档


先说一下简单的 Swagger 配置 web Api 


Swagger-UI本身只提供在线测试功能，要集成它还需要告诉它本项目提供的各种服务和参数信息。这里就需要一些工作量了，不过好在许多第三方库已经给我们完成了这一工作。我这里用的是Swashbuckle，使用它也比较简单，直接使用Nuget添加其程序包即可：

   1、初始化包  PM> Install-Package Swashbuckle

增加该程序包时，它本身会把自己相应的一些注册的代码添加到项目中，虽然我们可以不太关心这些操作，但有的时候还是需要修改一些相关的配置的。


2、初始化包后App_Start会添加 ，SwaggerConfig 代码如下：

using System.Web.Http;
using WebActivatorEx;
using WebApp;
using Swashbuckle.Application;

[assembly: PreApplicationStartMethod(typeof(SwaggerConfig), "Register")]

namespace WebApp
{
    public class SwaggerConfig
    {
        public static void Register()
        {
            var thisAssembly = typeof(SwaggerConfig).Assembly;

            GlobalConfiguration.Configuration
                .EnableSwagger(c =>
                    {
                        c.SingleApiVersion("v1", "WebApp");


                    })
                .EnableSwaggerUi(c =>
                {
                    GetXmlCommentsPath();
                });
        }
        private static string GetXmlCommentsPath()
        {
            return $@"{System.AppDomain.CurrentDomain.BaseDirectory}\\bin\\WebApi.XML";
        }
    }
}


3、集成XML注释

api 应用 ->右键->属性->生成->输出-配置XML


4、运行程序  地址栏请求：http://localhost:5746/swagger/       逼格很高啊




到此第一种方法完成   



开始改造第一种方法   删除SwaggerConfig    ，修改Startup 代码如下：

public partial class Startup
    {
        public void Configuration(IAppBuilder app)
        {
            ConfigureAuth(app);
            HttpConfiguration config = new HttpConfiguration();
            WebApiConfig.Register(config);
            config.EnableSwagger(c =>
            {
                c.SingleApiVersion("v1", "WebAPI");
                c.IncludeXmlComments(GetXmlCommentsPath());
                c.ResolveConflictingActions(x => x.First());

            }).EnableSwaggerUi();

            app.UseWebApi(config);
        }

        private static string GetXmlCommentsPath()
        {
            return $@"{System.AppDomain.CurrentDomain.BaseDirectory}\\bin\\WebApi.XML";
        }


会有这个问题 ：


解决方法如下：

you will need to import the Microsoft ASP.NET Web API 2 OWIN Self-Host Nuget package.


第一种方法改造完成，下面学习SwaggerUI 及Swagger Edit ，需要用到NodeJS ,下面是在网上找的配置方案，真的感谢

在团队开发中，一个好的 API 文档可以减少很多交流成本，也可以使一个新人快速上手业务。

前言

  • swagger ui是一个API在线文档生成和测试的利器，目前发现最好用的。
  • 为什么好用？Demo 传送门
    • 支持API自动生成同步的在线文档
      • 这些文档可用于项目内部API审核
      • 方便测试人员了解API
    • 这些文档可作为客户产品文档的一部分进行发布
      • 支持API规范生成代码，生成的客户端和服务器端骨架代码可以加速开发和测试速度

总结一句话就是好用，逼格高。下面我将总结一下如何快速在本地搭建一个基于Node和Swagger UI的 API 的文档工具

环境搭建

  • 下载Swagger UI（也可以直接下载 zip 文件）
git clone https://github.com/swagger-api/swagger-ui.git
  • 安装 express
  • 创建一个空文件夹node_app
mkdir node_app
  • 初始化 node ，创建package.json文件（）
➜  ~ ✗ >cd node_ap
➜  ~/node_app ✗ >npm init
// 下面的看你心情填写
name: (node_app) node_app
version: (1.0.0)
description:
entry point: (index.js)
test command:
git repository:
keywords:
author:
license: (ISC)
  • 安装 express
➜ ~/node_app git:(master) ✗ >npm install express --save

  • 创建 index.js ，手动创建就可以  vim不起作用   ，具体没理解啊
 ~/node_app git:(master) ✗ >vim index.js
  • 把下面代码贴如 index.js 中
var express = require('express');
var app = express();
app.get('/', function (req, res) {
  res.send('Hello World!');
});

app.listen(3000, function () {
  console.log('Example app listening on port 3000!');
});
  • 在 node_app 中创建空目录 public
➜  ~/node_app git:(master) ✗ >mkdir public
➜  ~/node_app git:(master) ✗ >cd public
 修改路由 
➜  ~/node_app/public git:(master) ✗ >vim ../index.js
//在文件第三行插入下面这句话
app.use('/static', express.static('public'));
把下载好的Swagger UI 文件中dist 目录下的文件全部复制到 public 文件夹下。