Swagger学习总结

时间 2019-12-18

标签 swagger 学习总结繁體版

原文原文链接

Swagger包含哪些东西？java

Swagger Tools
- Swagger Editorgit
  
  编辑器，能够实时生成API文档预览，并提供API接口测试。它包含了大部分Swagger的可用功能，好比生成实时文档，生成项目代码，API测试等等。github
- Swagger Codegenapache
  
  代码生成器。根据定义好的YAML文档生成不一样语言的项目代码。json
- Swagger UIapi
  
  API文档预览。app
- Swagger Inspectordom
  
  API测试。maven
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"] //自定义文档导出，["导出文件夹名", "导出文件名"]
    }
}