README

将 API 规范渲染为代码的工具。

安装

Phar

从 发布页面 下载 swac。

Docker

docker run --rm swaggest/swac swac --help

v0.1.28 swac
OpenAPI/Swagger compiler, https://github.com/swaggest/swac
Usage: 
   swac <action>
   action   Action name                                                      
            Allowed values: php-guzzle-client, go-client, js-client, markdown
...

示例

mkdir petstore && cd petstore
docker run -v $(pwd):/code -u 1000:1000 swaggest/swac swac php-guzzle-client https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v2.0/json/petstore.json --namespace MyApp\\Petstore

可以使用 - 作为文件路径通过 STDIN 传递模式。

cat ./openapi.json | docker run -i --rm swaggest/swac swac markdown -

Composer

安装 PHP Composer

composer global require swaggest/swac

用法

PHP 客户端

swac php-guzzle-client --help

v0.1.0 swac php-guzzle-client
OpenAPI/Swagger compiler, https://github.com/swaggest/swac
Usage: 
   swac php-guzzle-client <schemaPath> --namespace <namespace>
   schemaPath   Path/URL to OpenAPI/Swagger schema
   
Options: 
   --operations <operations>      Operations filter in form of comma-separated list of method/path, default empty
   --project-path <projectPath>   Path to project root, default ./                                               
   --namespace <namespace>        Project namespace

生成的客户端依赖于 swaggest/rest-client，guzzlehttp/guzzle 6 和 swaggest/json-schema。

示例.

Go 客户端

swac go-client --help 

v0.1.14 swac go-client
OpenAPI/Swagger compiler, https://github.com/swaggest/swac
Usage: 
   swac go-client <schemaPath>
   schemaPath   Path/URL to OpenAPI/Swagger schema
   
Options: 
   --operations <operations>               Operations filter in form of comma-separated list of method/path, default empty                  
   --out <out>                             Path to output package, default ./client                                                         
   --pkg-name <pkgName>                    Output package name, default "client"                                                            
   --skip-default-additional-properties    Do not add field property for undefined `additionalProperties`                                   
   --skip-do-not-edit                      Skip adding "DO NOT EDIT" comments                                                               
   --add-request-tags                      Add field tags with name and location to request structure properties, e.g. 'ID int `query:"id"`'
   --show-const-properties                 Show properties with constant values, hidden by default                                          
   --keep-parent-in-property-names         Keep parent prefix in property name, removed by default                                          
   --ignore-nullable                       Add `omitempty` to nullable properties, removed by default                                       
   --ignore-xgo-type                       Ignore `x-go-type` in schema to skip generation                                                  
   --with-zero-values                      Use pointer types to avoid zero value ambiguity                                                  
   --fluent-setters                        Add fluent setters to struct fields                                                              
   --ignore-required                       Ignore if property is required when deciding on pointer type or omitempty                        
   --renames <renames...>                  Map of exported symbol renames, example From:To                                                  
   --with-tests                            Generate (un)marshaling tests for entities (experimental feature)                                
   --require-xgenerate                     Generate properties with `x-generate: true` only                                                 
   --validate-required                     Generate validation code to check required properties during unmarshal                           

示例.

生成的客户端是一个没有外部依赖的单个包。

JavaScript 客户端

swac js-client --help 

v0.1.21 swac js-client
OpenAPI/Swagger compiler, https://github.com/swaggest/swac
Usage: 
   swac js-client <schema>
   schema   Path/URL to OpenAPI/Swagger schema
   
Options: 
   --operations <operations>      Operations filter in form of comma-separated list of method/path, default empty         
   --ignore-operation-id          Ignore operationId and always name operations using method and path                     
   --client-name <clientName>     Name of generated client class, default APIClient                                       
   --types-prefix <typesPrefix>   Prefix generated jsdoc class names                                                      
   --out <out>                    Path to output files, default ./client                                                  
   --patches <patches...>         JSON patches to apply to schema file before processing, merge patches are also supported

示例.

swac js-client openapi.json --out ./ --client-name Backend --types-prefix xh

生成的客户端是一个使用 XMLHttpRequest 和 jsdoc 类型定义的 ES5 类，没有外部依赖，适合在浏览器中直接使用。

Markdown

swac markdown --help

v0.1.24 swac markdown
OpenAPI/Swagger compiler, https://github.com/swaggest/swac
Usage: 
   swac markdown <schema>
   schema   Path/URL to OpenAPI/Swagger schema
   
Options: 
   --operations <operations>         Operations filter in form of comma-separated list of method/path, default empty         
   --ignore-operation-id             Ignore operationId and always name operations using method and path                     
   --client-name <clientName>        Name of generated client class, default APIClient                                       
   --add-schema-url <addSchemaUrl>   Add schema link to the document                                                         
   --types-prefix <typesPrefix>      Prefix generated type names                                                             
   --out <out>                       Path to output files, default ./client                                                  
   --patches <patches...>            JSON patches to apply to schema file before processing, merge patches are also supported
 

示例.

swac markdown openapi.json --out ./API-Docs.md --types-prefix xh