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"] //自定义文档导出，["导出文件夹名", "导出文件名"]
          }
      }