Swagger 与 OpenAPI 的历史来源：

Swagger 项目于 2015 年捐赠给 OpenAPI Initiative，此后被称为 OpenAPI。这两个名称可以互换使用。但是，“OpenAPI”指的是规范。“Swagger”是指来自 SmartBear 的符合 OpenAPI 规范的开源和商业产品系列。

简而言之：

  • OpenAPI 是一种规范。
  • Swagger 是使用 OpenAPI 规范的工具。例如，OpenAPIGenerator 和 SwaggerUI。

 OpenAPI 规范用于描述api的基本信息及功能。比如，API支持的http 方法，响应结果skema, 响应状态码等等。OpenAPI的声明定义方式可以通过json 和 yaml的方式，以下是通过yaml 描述api的一个基本例子。

  1. openapi: 3.0.0
  2. info:
  3.   title: Sample API
  4.   description: Optional multiline or single-line description in [CommonMark](http://commonmark.org/help/) or HTML.
  5.   version: 0.1.9
  6. servers:
  7.   - url: http://api.example.com/v1
  8.     description: Optional server description, e.g. Main (production) server
  9.   - url: http://staging-api.example.com
  10.     description: Optional server description, e.g. Internal staging server for testing
  11. paths:
  12.   /users:
  13.     get:
  14.       summary: Returns a list of users.
  15.       description: Optional extended description in CommonMark or HTML.
  16.       responses:
  17.         \'200\':    # status code
  18.           description: A JSON array of user names
  19.           content:
  20.             application/json:
  21.               schema: 
  22.                 type: array
  23.                 items: 
  24.                   type: string

 

Swashbuckle 包含三个主要组件：

  • Swashbuckle.AspNetCore.Swagger：Swagger 对象模型和中间件，用于将SwaggerDocument对象公开为 JSON 端点。

  • Swashbuckle.AspNetCore.SwaggerGen：一个 Swagger 生成器，可SwaggerDocument直接从您的路由、控制器和模型构建对象。它通常与 Swagger 端点中间件结合使用以自动公开 Swagger JSON。

  • Swashbuckle.AspNetCore.SwaggerUI：Swagger UI 工具的嵌入式版本。它解释 Swagger JSON 以构建丰富的、可定制的体验来描述 Web API 功能。它包括用于公共方法的内置测试工具。

将 Swagger 生成器添加到方法中的服务集合中Startup.ConfigureServices

  1. public void ConfigureServices(IServiceCollection services)
  2. {
  4.     // Register the Swagger generator, defining 1 or more Swagger documents
  5.     services.AddSwaggerGen();
  6. }

在该Startup.Configure方法中，启用中间件以提供生成的 JSON 文档和 Swagger UI：

  1. public void Configure(IApplicationBuilder app)
  2. {
  3.     // Enable middleware to serve generated Swagger as a JSON endpoint.
  4.     app.UseSwagger();
  6.     // Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.),
  7.     // specifying the Swagger JSON endpoint.
  8.     app.UseSwaggerUI(c =>
  9.     {
  10.         c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
  11.     });
  13.     ......
  14. }

 

在AddSwaggerGen 时，我们可以向其中传入参数 Action<SwaggerGenOptions> 这个参数，来声明我们如何创建OpenAPI 文档来描述我们的api。

  1.  services.AddSwaggerGen(c =>
  2.             {
    　　　　　　　　　　//声明文档的名字， title, version 等基本信息
  3.                 c.SwaggerDoc("v1", new OpenApiInfo { Title = "My Example APIs", Version = "v1" });
  4.                 c.CustomSchemaIds((type) => type.FullName);
    　　　　　　　　　　// 通过path 判断哪些api 应该被显示在文档上
  5.                 c.DocInclusionPredicate((docName, apiDescription) => apiDescription.RelativePath.Contains("api/v1"));
  6.                 
    　　             // 包含描述性的 xml 文档
    　　　　　　　　　　var xmlDoc = Path.Combine(AppContext.BaseDirectory, $"{this.GetType().Assembly.GetName().Name}.XML");
  7.                 if (File.Exists(xmlDoc))
  8.                     c.IncludeXmlComments(xmlDoc);
  9.             });

 

我们在之前的例子中，一直是对单个应用的单个文档，那么对于多个应用的文档，我们如何集中显示，方便开发人员查找与使用。

既然UseSwagger这个中间件可以帮助我们host生成的swagger json 文件，那么是不是我们通过一个application（api-explorer）来显示各个appplication的文档就可以，这能做到么？

答案是： 利用swagger的UI 前端文件。

这里给一个最basic的实现，使用的时候，可以各种定制化样式，加入请求验证等等；

  1.     <script src="./swagger-ui-bundle.js"> </script>
  2.     <script>
  3.           const apis = config.urls.sort((a, b) => a.name.localeCompare(b.name));
  4.           jwtToken = `Bearer ${token}`;
  5.           const ui = SwaggerUIBundle({
  6.             // 重中之重
  7.             urls: [{url, name}],
  8.             dom_id: \'#swagger-ui\',
  9.             deepLinking: true,
  10.             // Add jwt token to header start
  11.             requestInterceptor: function(request) {
  12.               request.headers.Authorization = jwtToken;
  13.               return request;
  14.             },
  15.             // Add jwt token to header finish
  16.             
  17.             layout: "StandaloneLayout"
  18.           })
  19.           window.ui = ui;
  20.         })
  21.       } 
  22.   </script>

我们可以通过配置文件的形式，注册好各个application的url，和它们各自的名字。

[{url: \’/a/a\’, name: \’aa\’}, {url: \’/b/b\’, name: \’bb\’}] 这种形式。

SwaggerUI 和 SwaggerUI bundle 可以接受的参数如链接，大家可以找到自己需要的参数去配置需要的功能。

swagger-ui/docs/usage/configuration.md

https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/configuration.md

—————————————————————————————————————————————————– 

欢迎大家讨论交流，指出不足，谢谢！

版权声明：本文为peppa-nan原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://www.cnblogs.com/peppa-nan/p/15046778.html