T O P

[资源分享]     .NET Core 中的 Swagger 应用与微服务场景下的Swagger Api 集成显示

  • By - 楼主

  • 2021-07-23 00:02:33
  • Swagger 与 OpenAPI 的历史来源:

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

    简而言之:

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

    1. OpenAPI

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

    openapi: 3.0.0
    info:
      title: Sample API
      description: Optional multiline or single-line description in [CommonMark](http://commonmark.org/help/) or HTML.
      version: 0.1.9
    servers:
      - url: http://api.example.com/v1
        description: Optional server description, e.g. Main (production) server
      - url: http://staging-api.example.com
        description: Optional server description, e.g. Internal staging server for testing
    paths:
      /users:
        get:
          summary: Returns a list of users.
          description: Optional extended description in CommonMark or HTML.
          responses:
            '200':    # status code
              description: A JSON array of user names
              content:
                application/json:
                  schema: 
                    type: array
                    items: 
                      type: string

     

    2. 单个项目中集成 Swashbuckle 

    Swashbuckle 包含三个主要组件:

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

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

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

    Basic 用法:

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

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

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

    public void Configure(IApplicationBuilder app)
    {
        // Enable middleware to serve generated Swagger as a JSON endpoint.
        app.UseSwagger();
    
        // Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.),
        // specifying the Swagger JSON endpoint.
        app.UseSwaggerUI(c =>
        {
            c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
        });
    
        ......
    }

     

    详细的Swagger 文档

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

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

     

    3. 微服务多应用的Swagger用法

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

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

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

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

        <script src="./swagger-ui-bundle.js"> </script>
        <script>
              const apis = config.urls.sort((a, b) => a.name.localeCompare(b.name));
              jwtToken = `Bearer ${token}`;
              const ui = SwaggerUIBundle({
                // 重中之重
                urls: [{url, name}],
                dom_id: '#swagger-ui',
                deepLinking: true,
                // Add jwt token to header start
                requestInterceptor: function(request) {
                  request.headers.Authorization = jwtToken;
                  return request;
                },
                // Add jwt token to header finish
                
                layout: "StandaloneLayout"
              })
              window.ui = ui;
            })
          } 
      </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

    ----------------------------------------------------------------------------------------------------------------------------------------------------- 

    欢迎大家讨论交流,指出不足,谢谢!

    本帖子中包含资源

    您需要 登录 才可以下载,没有帐号?立即注册