使用Swagger UI的Document和Test API

目录

介绍

配置

可视化

测试

支持属性 

支持XML文档

资源/材料/参考资料


介绍

开发人员通常通过浏览器请求或使用POSTMAN  Advanced Rest ClientARC)等客户端来测试API  。为了公开API的功能,我们还倾向于通过某些需要额外工作的方法公开方法和描述以及相关的数据结构。为了补充这些功能中的一个或两个,  Swagger  变得很方便,它通过配置提供API文档和API测试。

Swagger UI是一种可以跨API生命周期使用的工具。Swagger提供易于导航的文档和/API资源的可视化,并允许从应用程序本身内部与API交互,从而使开发和测试工作以及最终用户体验无缝顺畅。在本文中,我将讨论如何在API中实现swagger并举例说明Swagger UI的一些用例。我将使用.Net Core 2.0 Web API应用程序并使用Visual Studio 2017 IDE。我已经创建了一个带有单个控制器的示例API应用程序,并且有四个方法作为演示的一部分,可供下载

Swagger提供最强大,最易用的工具,以充分利用OpenAPI规范。 swagger.io

配置

应用程序上的接线Swagger相当小,可以通过四个简单步骤完成,即安装,导入,注册和端点启用。该软件包可以安装在软件包管理器控制台中,也可以通过转到NuGet软件包管理器菜单。

Install-Package Swashbuckle.AspNetCore

使用Swagger UI的Document和Test API_第1张图片

1:在Package Manager控制台中安装Swagger


安装完成后,必须将Swagger导入Startup.cs

using Swashbuckle.AspNetCore.Swagger;

然后必须在Startup.csConfigureServices方法中注册Swagger成为服务。

services.AddSwaggerGen(c =>

{

    c.SwaggerDoc(_version, new Info { Title = _applicationName, Version =   _version });

});

最后,应用程序必须在Startup.csConfigure 方法中为swagger启用JSONUI端点,以便最终用户可以通过Configure UIAPI方法交互。

// Enable Swagger JSON endpoint.
app.UseSwagger(); 
// Enable swagger-ui (HTML, JS, CSS, etc.)
app.UseSwaggerUI(c =>
{
     c.SwaggerEndpoint($"/swagger/{_version}/swagger.json",${_applicationName} {_version}"); 
});

代码段1中显示了Startup.cs文件的完整列表。

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Swashbuckle.AspNetCore.Swagger;

namespace Api
{
    public class Startup
    {
        private string _applicationName;
        private string _version;
        public Startup(IConfiguration configuration)
        {
            Configuration = configuration;
        }
        public IConfiguration Configuration { get; }
        
        public void ConfigureServices(IServiceCollection services)
        {
            services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1);
            var config = Configuration.GetSection("ApplicationSetting").Get();
            _applicationName = config.Name;
            _version = config.Version;

          // Register the Swagger
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc(_version, new Info { Title = _applicationName, Version = _version });
                // Set the comments path for the Swagger JSON and UI.
                var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
                var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
                c.IncludeXmlComments(xmlPath);
            });
        }

        public void Configure(IApplicationBuilder app, IHostingEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }
            else
            {
                app.UseHsts();
            }
           
            // Enable Swagger JSON endpoint.
            app.UseSwagger();
            // Enable swagger-ui (HTML, JS, CSS, etc.), with the Swagger JSON endpoint.
            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint($"/swagger/{_version}/swagger.json", $"{_applicationName} {_version}");
            });
            app.UseHttpsRedirection();
            app.UseMvc();
        }
    }
}

代码段1Startup.cs的内容

可视化

完成上述四个步骤后, swagger就准备好了。浏览https://localhost:5001/swagger/v1/swagger.json以获取JSON中的数据(在浏览器或客户端,如POSTMANAdvanced Rest ClientARC)。返回的JSON对象提供REST方法的规范(由控制器分隔)和API中使用的对象。一个示例响应是代码段2。

{
    "swagger": "2.0",
    "info": {
        "version": "v1",
        "title": "SmartStock API"
    },
    "paths": {
        "/api/Stock": {
            "get": {
                "tags": [
                    "Stock"
                ],
                "operationId": "GetStock",
                "consumes": [],
                "produces": [
                    "text/plain",
                    "application/json",
                    "text/json"
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success",
                        "schema": {
                            "uniqueItems": false,
                            "type": "array",
                            "items": {
                                "$ref": "#/definitions/Stock"
                            }
                        }
                    }
                }
            },
            "post": {
                "tags": [
                    "Stock"
                ],
                "operationId": "PostStock",
                "consumes": [
                    "application/json-patch+json",
                    "application/json",
                    "text/json",
                    "application/*+json"
                ],
                "produces": [
                    "text/plain",
                    "application/json",
                    "text/json"
                ],
                "parameters": [
                    {
                        "name": "stock",
                        "in": "body",
                        "required": false,
                        "schema": {
                            "$ref": "#/definitions/Stock"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success",
                        "schema": {
                            "$ref": "#/definitions/Stock"
                        }
                    }
                }
            }
        },
        "/api/Stock/{symbol}": {
            "get": {
                "tags": [
                    "Stock"
                ],
                "operationId": "GetStock",
                "consumes": [],
                "produces": [
                    "text/plain",
                    "application/json",
                    "text/json"
                ],
                "parameters": [
                    {
                        "name": "symbol",
                        "in": "path",
                        "required": true,
                        "type": "string"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success",
                        "schema": {
                            "uniqueItems": false,
                            "type": "array",
                            "items": {
                                "$ref": "#/definitions/Stock"
                            }
                        }
                    }
                }
            }
        },
        "/api/Stock/{id}": {
            "delete": {
                "tags": [
                    "Stock"
                ],
                "operationId": "DeleteStock",
                "consumes": [],
                "produces": [
                    "text/plain",
                    "application/json",
                    "text/json"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "type": "string",
                        "format": "uuid"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success",
                        "schema": {
                            "type": "boolean"
                        }
                    }
                }
            }
        },
        "/api/Values": {
            "get": {
                "tags": [
                    "Values"
                ],
                "operationId": "Get",
                "consumes": [],
                "produces": [
                    "text/plain",
                    "application/json",
                    "text/json"
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success",
                        "schema": {
                            "uniqueItems": false,
                            "type": "array",
                            "items": {
                                "type": "string"
                            }
                        }
                    }
                },
                "deprecated": true
            },
            "post": {
                "tags": [
                    "Values"
                ],
                "operationId": "Post",
                "consumes": [
                    "application/json-patch+json",
                    "application/json",
                    "text/json",
                    "application/*+json"
                ],
                "produces": [],
                "parameters": [
                    {
                        "name": "value",
                        "in": "body",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success"
                    }
                },
                "deprecated": true
            }
        },
        "/api/Values/{id}": {
            "get": {
                "tags": [
                    "Values"
                ],
                "operationId": "Get",
                "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": true
            },
            "put": {
                "tags": [
                    "Values"
                ],
                "operationId": "Put",
                "consumes": [
                    "application/json-patch+json",
                    "application/json",
                    "text/json",
                    "application/*+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": true
            },
            "delete": {
                "tags": [
                    "Values"
                ],
                "operationId": "Delete",
                "consumes": [],
                "produces": [],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "type": "integer",
                        "format": "int32"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success"
                    }
                },
                "deprecated": true
            }
        }
    },
    "definitions": {
        "Stock": {
            "type": "object",
            "properties": {
                "id": {
                    "format": "uuid",
                    "type": "string"
                },
                "ticker": {
                    "type": "string"
                },
                "company": {
                    "type": "string"
                },
                "price": {
                    "format": "double",
                    "type": "number"
                }
            }
        }
    }
}

代码段2JSON响应示例

可以通过导航到https://localhost:5001/swagger/index.html来访问Swagger UI   ,其中用户可以将JSON响应中可用的相同数据可视化为交互格式。此UI还支持其余方法的实际执行。

使用Swagger UI的Document和Test API_第2张图片

2:在Swagger UI中可视化API

测试

Swagger提供了在没有任何工具的情况下测试API方法的功能。例如,单击 GET(图2中的第一个选项卡)会扩展该方法。通过单击试一试然后执行swagger会触发对 /api/stock'get'方法的调用。请注意,演示应用程序中有一个名为“StockController”的控制器。结果显示在UI中,也可以下载。图3.显示了get方法的结果屏幕。UI中公开的任何方法都可以在UI本身中执行,从而使我们能够直接从API本身测试API。

使用Swagger UI的Document和Test API_第3张图片

3:在Swagger UI中测试API方法

支持属性 

默认情况下支持路由属性,Http *属性。图4显示了如何使用HttpGetHttpPostHttpDelete修饰的方法反映在Swagger UI中。

 

使用Swagger UI的Document和Test API_第4张图片

4:反映HTTP属性的Swagger UI


Swagger.Net中的属性同步。例如,如果使用[Obsolete]属性修饰控制器类,则UI反映控制器已过时的事实。图5显示ValuesController标记为Obsolete Swagger  UI反映相同且不可点击。当API在不破坏工作代码的情况下逐步取消某些功能时,此功能将变得非常方便。

使用Swagger UI的Document和Test API_第5张图片

5:反映Obsolte属性的Swagger UI

支持XML文档

Swagger支持UI中的文档,其中包含一些配置更改。通过在* .csproj文件中添加以下代码行,将生成XML文档。


     ....
     
          true
      
     
          $(NoWarn);1591
     

 使用Startup.cs中的以下代码行,在注册时,UI显示XML文档。

services.AddSwaggerGen(c => 
      {   
          ...
            var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
            var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile); 
            c.IncludeXmlComments(xmlPath);
}
);

 通过更改使用XML路径,SwaggerUI中公开XML文档。

使用Swagger UI的Document和Test API_第6张图片

6Swagger UI显示文档

Swagger在所有主流浏览器中都受支持,可在本地或Web环境中使用。UI的外观和风格是可定制的。

我之前展示了它如何在本地机器上运行。Swagger UI在云上运行良好。部署到Azure的相同应用程序, https://smartstockapi.azurewebsites.net/swagger/index.html 和在我的本地计算机上工作的一样。 

使用Swagger UI的Document和Test API_第7张图片

图7:云中托管的应用程序中的Swagger UI(Azure)

资源/材料/参考资料

swagger.io

开始使用SwashbuckleASP.NET Core

GitHub中的代码

 

原文地址:https://www.codeproject.com/Articles/1271949/Document-and-Test-API-with-Swagger-UI-2

你可能感兴趣的:(CSharp.NET,ASP.NET,CORE,Swagger,UI,ASP.NET,CORE)