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文件并用于集成。

比较实用的例子

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

Scheme别名：

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

对Enum类型使用驼峰命名：

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

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