qingstor/snips

A code generator for RESTful APIs.

Snips

A code generator for RESTful APIs.

Introduction

Snips generates various code using API specifications in OpenAPI Specification (Swagger) v2.0 format.

Run snips --help to get to help messages of snips.

$ snips --help
A code generator for RESTful APIs.

For example:
  $ snips -f ./specs/qingstor/api.json
          -t ./templates/qingstor/go \
          -o ./publish/qingstor-sdk-go/service
  $ ...
  $ snips --file=./specs/qingstor/api.json \
          --template=./templates/qingstor/ruby \
          --output=./publish/qingstor-sdk-ruby/lib/qingstor/sdk/service
  $ ...

Copyright (C) 2016 Yunify, Inc.

Usage:
  snips [flags]

Flags:
  -f, --file string       Specify the spec file.
      --format string     Specify the format of spec file. (default "OpenAPI-v2.0")
  -o, --output string     Specify the output directory.
  -t, --template string   Specify template files directory.
  -v, --version           Show version.

Installation

Snips is a command line tool, and it's easy to have it installed. You can build it from source code or download the precompiled binary directly.

Install from Source Code

Snips requires Go 1.6 or later's vendor feature, the dependencies the project used are included in the vendor directory. And we use glide to manage project dependence.

$ git clone [email protected]:yunify/snips.git
$ glide install
$ make install

Notice: You can also use Go 1.5 with the GO15VENDOREXPERIMENT=1.

Download Precompiled Binary

0. Go to releases tab and download the binary for your operating system, for example snips-v0.0.7-darwin_amd64.tar.gz.
1. Unarchive the downloaded file, and put the executable file snips into a directory that in the $PATH environment variable, for example /usr/local/bin.
2. Run snips --help to get started.

SDK Development Workflow

Snips takes API specifications and template to generate lots of code for APIs, then these generated code plus the handcrafted code makes up the SDK. Next, we use scenario based test to make sure our SDKs are working properly, and ensure their functional consistency.

+---------------------------------------------+--------------------+
|                                             |  Workflow Diagram  |
|       API Specifications                    +--------------------|
|                   +                                              |
|                   |                               Scenario       |
|     Templates     |               +------------->  Based         |
|         +         |      +------>SDKs             Testing        |
|         |         |      |        ^                  +           |
|         |         v      |        |                  |           |
|         +-----> Snips+---+        |                  |           |
|                                   |                  |           |
|                                   |                  v           |
|       Handcraft+------------------+               Publish        |
|                                                                  |
+------------------------------------------------------------------+

Add an SDK for Another Programing Language

0. Create handcraft files of SDK, to handle configuration, network request and etc.
1. Writing templates for API code.
2. Generate code using snips.
3. Running tests.
4. Publish.

Update an Exists SDK

0. Change handcraft files (if needed) and update the API specs.
1. Regenerate code.
2. Running tests.
3. Publish.

Example

Let's take Go SDK for QingStor (qingstor-sdk-go) for example.

Prepare

• ./specs/qingstor: Refer to the QingStor API specifications
• ./test/features: Refer to the QingStor SDK test scenarios

Tips: Include these files as git submodule.

Procedures

0. Create template files which will be used to generate API code in ./template.

1. Generate code using snips, and format the generated code.

   $ snips --version
   snips version 0.3.6
   $ snips -f ./specs/qingstor/2016-01-06/swagger/api_v2.0.json \
           -t ./template \
           -o ./service
   Loaded templates from ./template
   4 template(s) detected.
   Loaded specification file ./specs/qingstor/2016-01-06/swagger/api_v2.0.json (Swagger-v2.0)
   
   Generating to: ./service/qingstor.go
   Generating to: ./service/bucket.go
   Generating to: ./service/object.go
   Generating to: ./service/types.go
   
   Everything looks fine.
   $ gofmt -w .

2. Implement test scenarios in ./test.

   $ ls ./test
   bucket.go                 config.yaml.example       test_config.yaml
   bucket_acl.go             features                  test_config.yaml.example
   bucket_cors.go            main.go                   utils.go
   bucket_external_mirror.go object.go                 vendor
   bucket_policy.go          object_multipart.go
   config.yaml               service.go

3. Running scenarios test, and pass all tests.

   $ pushd ./test
   $ go run *.go
   ...
   38 scenarios (38 passed)
   84 steps (84 passed)
   1m2.408357076s
   $ popd

4. Every time the QingStor API changes, just update the specs/qingstor and ./test/features submodule and regenerate code. Then add/change test for this API change, and rerun the online test to make sure the SDK is working properly.

References

• QingStor API Specs
• QingStor SDK Test Scenarios

Contributing

Please see Contributing Guidelines of this project before submitting patches.

LICENSE

The Apache License (Version 2.0, January 2004).

snips's Issues

Use go modules instead

qingcloud-sdk-go 升级遇到问题

snips version 0.2.3

之前的 qingcloud-sdk-go 是基于 snips 0.0.9 版本生成.

snips 0.2 之后模板的结构有发生变化.

针对生成代码时产生的问题, 对 qingcloud-sdk-go 的模板文件做了更新.

qingcloud-sdk-go/template/shared.tmpl 的更新 (137-248行):

type {{$opID}}Output struct {
	Message *string `json:"message" name:"message"`
-		{{- if $operation.Response.Elements.Properties | len -}}
-			{{$data := $operation.Response.Elements}}
-			{{template "RenderProperties" passThrough $data `location:"elements"`}}
+		{{- range $keyStatus, $valueStatus := $operation.Responses -}}
+			{{- if $valueStatus.Elements.Properties | len -}}
+				{{$data := $valueStatus.Elements}}
+				{{template "RenderProperties" passThrough $data `location:"elements"`}}
+			{{- end -}}
+
	{{- end -}}
}
{{end}}

上面的修改修复了 snips 生成代码时的错误提升.

导致输出的文件发生变化. 下面是 service/cache.go 发生的变化的片段(74-82行):

type AddCacheNodesInput struct {
-	Cache      *string           `json:"cache" name:"cache" location:"params"`           // Required
-	NodeCount  *int              `json:"node_count" name:"node_count" location:"params"` // Required
-	PrivateIPs []*CachePrivateIP `json:"private_ips" name:"private_ips" location:"params"`
+	Cache      *string       `json:"cache" name:"cache" location:"params"`           // Required
+	NodeCount  *int          `json:"node_count" name:"node_count" location:"params"` // Required
+	PrivateIPs []interface{} `json:"private_ips" name:"private_ips" location:"params"`
}

其中 PrivateIPs 的类型退化为 []interface{}

命令参数:

snips -f /Users/chai/go/src/github.com/yunify/qingcloud-api-specs/2013-08-30/swagger/api_v2.0.json -t /Users/chai/go/src/github.com/yunify/qingcloud-sdk-go/template -o ./qingcloud-sdk-go
Loaded templates from /Users/chai/go/src/github.com/yunify/qingcloud-sdk-go/template
4 template(s) detected.
Loaded specification file /Users/chai/go/src/github.com/yunify/qingcloud-api-specs/2013-08-30/swagger/api_v2.0.json (Swagger-v2.0)

Could you please update readme

Could you please help update readme accordingly？

a few parameters are deprecated. e.g. --service

But I still found these params in sample section

Thanks!

UUID should be added into words list

/home/xuanwo/Code/go/src/github.com/yunify/qingcloud-sdk-go/service/types.go:410:2: struct field GlobalUuid should be GlobalUUID

Add more dubug info

snips next

• Generate code by default
• Pluggable logic