Swagger UI教程 API 文档神器 搭配Node使用 web api 接口文档 (转)
http://www.68idc.cn/help/makewebs/qitaasks/20160621620667.html
两种方案 一、Swagger 配置 web Api 接口文档美化 二、通过NodeJS 发布Swagger UI 配置api 文档 先说一下简单的 Swagger 配置 web Api Swagger-UI 本身只提供在线测试功能，要集成它还需要告诉它本项目提供的各种服务和参数信息。
两种方案
一、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 ,下面是在网上找的配置方案，真的感谢
交流成本
前言
- swagger ui是一个API在线文档生成和测试的利器，目前发现最好用的。
- 为什么好用？Demo 传送门
- 支持API自动生成同步的在线文档
- 这些文档可用于项目内部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 文件夹下。
开启
node
<span style="font-size:18px;color:#cc0000;"> ~/node_app git:(master) ? >node index.js</span>
- 打开浏览器，输入http://localhost:3000/static/index.html
到此为止，你已经把官方的 demo 在本地配置好了。当然你也可以吧这个搭建在服务器上
编写文档并发布
- 使用Swagger Editor编写 API 文档
- Swagger Editor 上的是基于 yaml 的语法，但是不用害怕，看着官方的 demo 看个10分钟就会了。
- 导出 test.json 文档
- 把 test.json 放到 node_app/public 目录下。
- 利用编辑器修改
url = "http://petstore.swagger.io/v2/swagger.json";为url = "/static/test.json"; - 重启 node 服务，浏览器中打开
http://localhost:3000/static/index.html就是你自己写的 api 文档了
效果图
到此效果出来了，还没有完 ，我配置的是 Web Api 和MVC
test.json 代码如下：做一下概要的说明
{
"swagger": "2.0",
"info": {
"title": "Uber API",
"description": "Move your app forward with the Uber API",
"version": "1.0.0"
},
"host": "115.29.161.201:8077/",
"schemes": [
"http"
],
"basePath": "/api",
"produces": [
"application/json"
],
"paths": {
"/products": {
"get": {
"summary": "Product Types",
"description": "The Products endpoint returns information about the *Uber* products\noffered at a given location. The response includes the display name\nand other details about each product, and lists the products in the\nproper display order.\n",
"parameters": [
{
"name": "latitude",
"in": "query",
"description": "Latitude component of location.",
"required": true,
"type": "number",
"format": "double"
},
{
"name": "longitude",
"in": "query",
"description": "Longitude component of location.",
"required": true,
"type": "number",
"format": "double"
}
],
"tags": [
"Products"
],
"responses": {
"200": {
"description": "An array of products",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/Product"
}
}
},
"default": {
"description": "Unexpected error",
"schema": {
"$ref": "#/definitions/Error"
}
}
}
}
},
"/estimates/price": {
"get": {
"summary": "Price Estimates",
"description": "The Price Estimates endpoint returns an estimated price range\nfor each product offered at a given location. The price estimate is\nprovided as a formatted string with the full price range and the localized\ncurrency symbol.<br><br>The response also includes low and high estimates,\nand the [ISO 4217](http://en.wikipedia.org/wiki/ISO_4217) currency code for\nsituations requiring currency conversion. When surge is active for a particular\nproduct, its surge_multiplier will be greater than 1, but the price estimate\nalready factors in this multiplier.\n",
"parameters": [
{
"name": "start_latitude",
"in": "query",
"description": "Latitude component of start location.",
"required": true,
"type": "number",
"format": "double"
},
{
"name": "start_longitude",
"in": "query",
"description": "Longitude component of start location.",
"required": true,
"type": "number",
"format": "double"
},
{
"name": "end_latitude",
"in": "query",
"description": "Latitude component of end location.",
"required": true,
"type": "number",
"format": "double"
},
{
"name": "end_longitude",
"in": "query",
"description": "Longitude component of end location.",
"required": true,
"type": "number",
"format": "double"
}
],
"tags": [
"Estimates"
],
"responses": {
"200": {
"description": "An array of price estimates by product",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/PriceEstimate"
}
}
},
"default": {
"description": "Unexpected error",
"schema": {
"$ref": "#/definitions/Error"
}
}
}
}
},
"/estimates/time": {
"get": {
"summary": "Time Estimates",
"description": "The Time Estimates endpoint returns ETAs for all products offered at a given location, with the responses expressed as integers in seconds. We recommend that this endpoint be called every minute to provide the most accurate, up-to-date ETAs.",
"parameters": [
{
"name": "start_latitude",
"in": "query",
"description": "Latitude component of start location.",
"required": true,
"type": "number",
"format": "double"
},
{
"name": "start_longitude",
"in": "query",
"description": "Longitude component of start location.",
"required": true,
"type": "number",
"format": "double"
},
{
"name": "customer_uuid",
"in": "query",
"type": "string",
"format": "uuid",
"description": "Unique customer identifier to be used for experience customization."
},
{
"name": "product_id",
"in": "query",
"type": "string",
"description": "Unique identifier representing a specific product for a given latitude & longitude."
}
],
"tags": [
"Estimates"
],
"responses": {
"200": {
"description": "An array of products",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/Product"
}
}
},
"default": {
"description": "Unexpected error",
"schema": {
"$ref": "#/definitions/Error"
}
}
}
}
},
"/me": {
"get": {
"summary": "User Profile",
"description": "The User Profile endpoint returns information about the Uber user that has authorized with the application.",
"tags": [
"User"
],
"responses": {
"200": {
"description": "Profile information for a user",
"schema": {
"$ref": "#/definitions/Profile"
}
},
"default": {
"description": "Unexpected error",
"schema": {
"$ref": "#/definitions/Error"
}
}
}
}
},
"/Values/Get/": {
"get": {
"summary": "Values Profile",
"description": "自己测试",
"parameters": [
{
"name": "id",
"in": "query",
"description": "Latitude component of start location.",
"required": true,
"type": "number",
"format": "int32"
}],
"tags": [
"Values"
],
"responses": {
"200": {
"description": "值得概要信息",
"schema": {
"$ref": "#/definitions/valuesget"
}
},
"default": {
"description": "意外错误",
"schema": {
"$ref": "#/definitions/Error"
}
}
}
}
},
"/history": {
"get": {
"summary": "User Activity",
"description": "The User Activity endpoint returns data about a user's lifetime activity with Uber. The response will include pickup locations and times, dropoff locations and times, the distance of past requests, and information about which products were requested.<br><br>The history array in the response will have a maximum length based on the limit parameter. The response value count may exceed limit, therefore subsequent API requests may be necessary.",
"parameters": [
{
"name": "offset",
"in": "query",
"type": "integer",
"format": "int32",
"description": "Offset the list of returned results by this amount. Default is zero."
},
{
"name": "limit",
"in": "query",
"type": "integer",
"format": "int32",
"description": "Number of items to retrieve. Default is 5, maximum is 100."
}
],
"tags": [
"User"
],
"responses": {
"200": {
"description": "History information for the given user",
"schema": {
"$ref": "#/definitions/Activities"
}
},
"default": {
"description": "Unexpected error",
"schema": {
"$ref": "#/definitions/Error"
}
}
}
}
}
},
"definitions": {
"Product": {
"type": "object",
"properties": {
"product_id": {
"type": "string",
"description": "Unique identifier representing a specific product for a given latitude & longitude. For example, uberX in San Francisco will have a different product_id than uberX in Los Angeles."
},
"description": {
"type": "string",
"description": "Description of product."
},
"display_name": {
"type": "string",
"description": "Display name of product."
},
"capacity": {
"type": "string",
"description": "Capacity of product. For example, 4 people."
},
"image": {
"type": "string",
"description": "Image URL representing the product."
}
}
},
"PriceEstimate": {
"type": "object",
"properties": {
"product_id": {
"type": "string",
"description": "Unique identifier representing a specific product for a given latitude & longitude. For example, uberX in San Francisco will have a different product_id than uberX in Los Angeles"
},
"currency_code": {
"type": "string",
"description": "[ISO 4217](http://en.wikipedia.org/wiki/ISO_4217) currency code."
},
"display_name": {
"type": "string",
"description": "Display name of product."
},
"estimate": {
"type": "string",
"description": "Formatted string of estimate in local currency of the start location. Estimate could be a range, a single number (flat rate) or \"Metered\" for TAXI."
},
"low_estimate": {
"type": "number",
"description": "Lower bound of the estimated price."
},
"high_estimate": {
"type": "number",
"description": "Upper bound of the estimated price."
},
"surge_multiplier": {
"type": "number",
"description": "Expected surge multiplier. Surge is active if surge_multiplier is greater than 1. Price estimate already factors in the surge multiplier."
}
}
},
"Profile": {
"type": "object",
"properties": {
"first_name": {
"type": "string",
"description": "First name of the Uber user."
},
"last_name": {
"type": "string",
"description": "Last name of the Uber user."
},
"email": {
"type": "string",
"description": "Email address of the Uber user"
},
"picture": {
"type": "string",
"description": "Image URL of the Uber user."
},
"promo_code": {
"type": "string",
"description": "Promo code of the Uber user."
}
}
},
"Activity": {
"type": "object",
"properties": {
"uuid": {
"type": "string",
"description": "Unique identifier for the activity"
}
}
},
"valuesget": {
"type": "object",
"properties": {
"Vanme": {
"type": "string",
"description": "名字"
}
}
},
"Activities": {
"type": "object",
"properties": {
"offset": {
"type": "integer",
"format": "int32",
"description": "Position in pagination."
},
"limit": {
"type": "integer",
"format": "int32",
"description": "Number of items to retrieve (100 max)."
},
"count": {
"type": "integer",
"format": "int32",
"description": "Total number of items available."
},
"history": {
"type": "array",
"items": {
"$ref": "#/definitions/Activity"
}
}
}
},
"Error": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"format": "int32"
},
"message": {
"type": "string"
},
"fields": {
"type": "string"
}
}
}
}
}
host：配置程序发布地址
schemes ：请求方式 http 或者https
tags：页签名称
其他的看个10分钟作用的基本就明白了
我请求web api 遇到了一个跨域的问题 ，永远显示 no content ，没有response
F12 看了一下
解决办法修改web.config
<system.webServer>
<httpProtocol>
<customHeaders>
<add name="Access-Control-Allow-Origin" value="*" />
<add name="Access-Control-Allow-Headers" value="Content-Type" />
<add name="Access-Control-Allow-Methods" value="GET, POST, PUT, DELETE, OPTIONS" />
</customHeaders>
</httpProtocol>
<handlers>
<remove name="ExtensionlessUrlHandler-Integrated-4.0" />
<remove name="OPTIONSVerbHandler" />
<remove name="TRACEVerbHandler" />
<add name="ExtensionlessUrlHandler-Integrated-4.0" path="*." verb="*" type="System.Web.Handlers.TransferRequestHandler" preCondition="integratedMode,runtimeVersionv4.0" />
</handlers>
</system.webServer>
还不行的话检查一下api 是否有设置了特性 ，网上查了一下，还要在api文件中添加如下方法
//public string Options()
//{ // return null; // HTTP 200 response with empty body //}
我没有添加也成功了
Swagger UI教程 API 文档神器 搭配Node使用 web api 接口文档 (转)的更多相关文章
- Swagger UI教程 API 文档神器 搭配Node使用
ASP.NET Web API 使用Swagger生成在线帮助测试文档 Swagger 生成 ASP.NET Web API 前言 swagger ui是一个API在线文档生成和测试的利器,目前发现最 ...
- 【ASP.NET Web API教程】3.2 通过.NET客户端调用Web API（C#）
原文:[ASP.NET Web API教程]3.2 通过.NET客户端调用Web API(C#) 注:本文是[ASP.NET Web API系列教程]的一部分,如果您是第一次看本博客文章,请先看前面的 ...
- 【ASP.NET Web API教程】1.1 第一个ASP.NET Web API
Your First ASP.NET Web API (C#)第一个ASP.NET Web API(C#) By Mike Wasson|January 21, 2012作者:Mike Wasson ...
- 使用 Swagger 自动生成 ASP.NET Core Web API 的文档、在线帮助测试文档（ASP.NET Core Web API 自动生成文档）
对于开发人员来说,构建一个消费应用程序时去了解各种各样的 API 是一个巨大的挑战.在你的 Web API 项目中使用 Swagger 的 .NET Core 封装 Swashbuckle 可以帮助你 ...
- 一文了解.Net Core 3.1 Web API基础知识
一.前言 随着近几年前后端分离.微服务等模式的兴起,.Net Core也似有如火如荼之势 ,自16年发布第一个版本到19年底的3.1 LTS版本,以及将发布的.NET 5,.NET Core一路更迭, ...
- Asp.Net Web API 2第十三课——ASP.NET Web API中的JSON和XML序列化
前言 阅读本文之前,您也可以到Asp.Net Web API 2 系列导航进行查看 http://www.cnblogs.com/aehyok/p/3446289.html 本文描述ASP.NET W ...
- Create an OData v4 Endpoint Using ASP.NET Web API 2.2（使用ASP.NET Web API 2.2创建OData v4端点）
开放数据协议Open Data Protocol(OData)是web的一种数据存取协议,OData通过设置CRUD操作(Create创建.Read读取.Update更新,Delete删除)提供一种统 ...
- Create a REST API with Attribute Routing in ASP.NET Web API 2
原文:http://www.asp.net/web-api/overview/web-api-routing-and-actions/create-a-rest-api-with-attribute- ...
- Swagger UI教程
文档源地址 http://www.68idc.cn/help/makewebs/qitaasks/20160621620667.html Swagger-UI本身只提供在线测试功能,要集成它还需要告诉 ...
- Web API使用记录系列（三）Web API与Owin
还好在坚持,今天继续更新第三篇随笔----使用owin来启动WebAPI(这里还是以IIS为宿主,当然也可以使用别的如Console.Windows Server等) 关于OWIN(Open Web ...
随机推荐
- c语言学习---void 数据类型
这样的语法是错误的: void a = 10; void表示无类型, 这样定义一个变量a, 编译器是无法知道给a分配多大的内存空间的 #include<stdio.h> #include ...
- django.core.exceptions.ImproperlyConfigured: Requested setting INSTALLED_APPS, but settings are not configured. You must either define the environment variable DJANGO_SETTINGS_MODULE or call settings.
import os if __name__ == '__main__': # 下面的autoUI改成你当前的项目名称 os.environ.setdefault("DJANGO_SETTIN ...
- Docker-Compose实战<下篇>
本文是在上一篇文章的基础上做的一些内容追加,上文最后截止内容是docker-compose build将镜像生成完成.接下来我将继续写启动相关服务,访问服务以及常用命令使用等. 1 启动镜像 使用命令 ...
- （读书笔记）基于CMMI的软件工程及实训指导------第一章软件工程基础
第一章------软件工程基础 1.软件工程基本原理 (1)按照软件生命周期的阶段划分制订计划,严格依据计划进行管理 (2)坚持进行阶段评审 (3)实行严格的产品控制 (4)采用现代程序设计技术 (5 ...
- py打包工具
库地址: auto-py-to-exe https://pypi.org/project/auto-py-to-exe/ Gooey https://pypi.org/project/Gooey/ 为 ...
- Mac如何用鼠标快速锁屏
锁屏谁不会啊?本来写这篇文章,感觉自己太多余,但用鼠标直接锁屏就有点小意思,Mac对于很多人来说非常模式,通常是商务.设计这类人事在使用,对于新手而言,它的功能过于隐藏,那么Mac要如何达到快速锁屏呢 ...
- Docker--搭建 Python + Pytest +Allure 的自动化测试环境
本文参考:https://www.cnblogs.com/poloyy/p/13954637.html 下载Jenkins镜像 docker search jenkins 推荐使用第二个:docker ...
- Software--BigData--StreamingData
2018-03-29 16:13:34 一 : 流系统分层架构设计 二: 分层技术选型分析 三:底层 -- 服务配置和协调 ZooKeeper
- three.js基础用法
import * as THREE from '../libs/build/three.module.js'; import { OrbitControls } from '../libs/jsm/c ...
- mycat分片的十四种算法
MyCat的分片规则配置在 conf目录下的 rule.xml文件中定义 ; 环境准备 : schema.xml中的内容做好备份 , 并配置 逻辑库; <schema name="PA ...