.NET Core 中的 Swagger 應用與微服務場景下的Swagger Api 整合顯示

懶懶的佩奇發表於2021-07-22
Swagger微服務API

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

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

歡迎大家討論交流，指出不足，謝謝！

相關文章