Swagger學習總結

Swagger包含哪些東西？

• Swagger Tools

  • Swagger Editor

    編輯器，可以實時生成API文檔預覽，並提供API接口測試。它包含了大部分Swagger的可用功能，比如生成實時文檔，生成項目代碼，API測試等等。

  • Swagger Codegen

    代碼生成器。根據定義好的YAML文檔生成不同語言的項目代碼。

  • Swagger UI

    API文檔預覽。

  • Swagger Inspector

    API測試。

• Swagger Hub

  收費，一整套API開發、管理、協作、測試的解決方案。

• 集成

  Swagger Tools里面的功能都是由更小的“組件”拼接而成的，我們可以按需把這些組件集成到實際項目中去。

  • （TypeScript）NSwag
  • （.NET）Swashbuckle

  • （.NET CORE）Swashbuckle.AspNetCore，它主要包含2個部分

    • Swagger：基礎庫，提供基礎功能

    • SwaggerGen：生成類，可做很多自定義的文檔輸出。

    • SwaggerUI：UI類，提供默認UI以及各種UI擴展。

    • Cli：目前是beta版。可以實時從當前application得到swagger json文件並用於集成。

    • 比較實用的例子

      1. 版本控制：[ApiExplorerSettings(GroupName = "v2")]

      2. Scheme別名：

         services.AddSwaggerGen(c =>
         {
             ...
             c.CustomSchemaIds((type) => type.FullName);
         };

          

      3. 對Enum類型使用駝峰命名：

         services.AddSwaggerGen(c =>
         {
             ...
             c.DescribeAllEnumsAsStrings();
             c.DescribeStringEnumsInCamelCase();
         };

          

      4. 給API上指定的Attribute（比如給所有HttpPost標注的API添加500,404返回類型）批量添加Response Type

         public void Apply(Operation operation, OperationFilterContext context)
         {
             var attrPost = context.ApiDescription
                 .ControllerAttributes()
                 .Union(context.ApiDescription.ActionAttributes())
                 .OfType<HttpPostAttribute>();
         
             if (attrPost.Any())
             {
                 operation.Responses.Add("500", new Response { Description = "Server Internal Error CJ" });
                 operation.Responses.Add("404", new Response { Description = "Cannot Find CJ" });
             }
         }
         
         services.AddSwaggerGen(c =>
         {
             c.OperationFilter<CommonResponseFilter>();
         });

         對所有的controller和action批量操作

         public class SecurityRequirementsOperationFilter : IOperationFilter
         {
             public void Apply(Operation operation, OperationFilterContext context)
             {
                 // Policy names map to scopes
                 var controllerScopes = context.ApiDescription.ControllerAttributes()
                     .OfType<AuthorizeAttribute>()
                     .Select(attr => attr.Policy);
         
                 var actionScopes = context.ApiDescription.ActionAttributes()
                     .OfType<AuthorizeAttribute>()
                     .Select(attr => attr.Policy);
         
                 var requiredScopes = controllerScopes.Union(actionScopes).Distinct();
         
                 if (requiredScopes.Any())
                 {
                     operation.Responses.Add("401", new Response { Description = "Unauthorized" });
                     operation.Responses.Add("403", new Response { Description = "Forbidden" });
         
                     operation.Security = new List<IDictionary<string, IEnumerable<string>>>();
                     operation.Security.Add(new Dictionary<string, IEnumerable<string>>
                     {
                         { "oauth2", requiredScopes }
                     });
                 }
             }
         }

  • Swagger Code Generator

    • 對於Windows用戶，下載完Wget后，將Wget.exe的路徑添加到系統環境變量。
    • 安裝Maven打包工具，用於修改模板之后的打包工作。JAVA_HOME, M2_HOME相關的環境變量必須配置。
    • （可選）下載swagger-codegen-cli.jar（也可直接下載swagger codegen源碼后，用maven或eclips編譯獲得）

      wget http://central.maven.org/maven2/io/swagger/swagger-codegen-cli/2.3.1/swagger-codegen-cli-2.3.1.jar -O swagger-codegen-cli.jar

      
    • 查詢支持的語言

      java -jar swagger-codegen-cli.jar help
      java -jar swagger-codegen-cli.jar langs

    • 生成C#默認模板

      java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate -i http://petstore.swagger.io/v2/swagger.json -l csharp -o samples/client/petstore/csharp

    • 自定義模板

      swagger是通過mustache模板來生成對應的代碼的。

      1. 通過jar包來生成初始化模板工程

         java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar meta -o output/novasoftwareLib -n novasoftware -p com.novasoftware.codegen

         參照ReadMe.md文件的提示做模板修改

      2. 編譯並打包該模板（例子中是novasoftwareLib工程）

         tips：編譯時，使用Maven Goals=compile或package

      3. 打包成功后生成jar文件，執行cmd命令，代碼將根據模板自動生成到當前目錄下的novasoftwareClient文件夾中。
         

         java -cp output/novasoftwareLib/target/novasoftware-swagger-codegen-1.0.0.jar;modules/swagger-codegen-cli/target/swagger-codegen-cli.jar io.swagger.codegen.SwaggerCodegen generate -l novasoftware -i http://petstore.swagger.io/v2/swagger.json -o novasoftwareClient

      4. Coevery中的codegen優點：把模板路徑和模板文件暴露了出來，方便隨時修改。

    • 自定義生成器配置

      通過配置config.json來自定義模板的生成。

      java -cp output/novasoftwareLib/target/novasoftware-swagger-codegen-1.0.0.jar;modules/swagger-codegen-cli/target/swagger-codegen-cli.jar io.swagger.codegen.SwaggerCodegen generate -l novasoftware -i http://petstore.swagger.io/v2/swagger.json -o novasoftwareClient -c path/to/config.json

      針對不同的開發語言，config有不同的option可以配置，通過以下命名查詢

      java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar config-help -l csharp

      針對不同的開發語言，swagger有專門對應的map映射，我們可以在以下路徑中找到對應語言的映射規則。

      modules/swagger-codegen/src/main/java/io/swagger/codegen/languages/*

      附CoeveryCodegen的config.json文件例子：

      {
      
          "outputFolder": "output", //自動生成代碼的根目錄
          "templateDir": "./codegen-templates/coevery-backend", //模板文件*.mustache存放路徑
          "packageName": "com.novasoftware.Coevery", //生成代碼的命名空間
          "modelPackage": "Models", //Model類導出時的文件夾
          "apiPackage": "Api", //API類導出時的文件夾
          "additionalProperties": {
              "apiVersion": "V2", //自定義模板靜態變量，可直接在mustache中使用。{{apiVersion}}，輸出結果：V2
              "ceejay": "Chen Jun" //自定義模板靜態變量，可直接在mustache中使用，{{ceejay}}，輸出結果：Chen Jun
          },
          "modelTemplateFiles": {
              "model.mustache": ".cs" //指定Model類模板以及導出文件擴展名
          },
          "apiTemplateFiles": {
              "api.mustache": ".cs" //指定API類模板以及導出文件擴展名
          },
          "supportingFiles": {
              "myFile.mustache": ["", "myFile.cs"] //自定義文檔導出，["導出文件夾名", "導出文件名"]
          }
      }