CF-Swagger

Collection of Swagger descriptions and applications for CloudFoundry APIs.

This tool is licensed under the Apache 2.0 OSS license. We'd love to hear from you if you are using, attempting to use, or planning to use this tool.

Two additional ways, besides Gitter or Slack chat above, to contact us:

1. Feel free to open an issue (good or bad) here on Github.
2. Send email to cloudfoundry.swagger at the Gmail domain.

Getting Started

Overview Presentations, Talks, Blogs

• Overview presentation on September 16th, 2015. Slides (PDF and PPTX), video

Getting Started

Assuming you have a valid Golang 1.4.2 or later installed for your system, you can quickly get the version that we are using for go-swagger. This version is on Github. This is an extension of go-swagger. You can use the bin/build file to generate the binary or directly use our swagger binary from out folder.

The tests that we are generating are tested on Go Service Broker. You need to follow the steps indicated in the README.md of the project to build the broker and then run it.

Cloning and Building

Clone this repo and build it. Using the following commands on a Linux or Mac OS X system:

$ mkdir -p cf-swagger/src/github.com/maximilien
$ export GOPATH=$(pwd)/cf-swagger:$GOPATH
$ cd cf-swagger/src/github.com/maximilien
$ git clone https://github.com/maximilien/cf-swagger.git
$ cd cf-swagger
$ ./bin/build

NOTE: if you get any dependency errors, then use go get path/to/dependency to get it, e.g., go get github.com/onsi/ginkgo and go get github.com/onsi/gomega

Generating and Running Tests

You should generate the tests using the last API specification JSON file. You can do this with: $ ./bin/generate_service_broker_test in your cloned repository. This assumes that you already cloned and built go-swagger.

The output should be similar to:

$ ./bin/generate_service_broker_test
Swagger generating code
======>  Adding TCK To TEST
2015/09/17 17:30:03 rendered tck template: operationstck_reporter
2015/09/17 17:30:03 rendered suite test template: operationsServiceBroker_suite_test
2015/09/17 17:30:03 rendered test template: createServiceInstance
2015/09/17 17:30:03 rendered test template: serviceBind
2015/09/17 17:30:03 rendered test template: updateServiceInstance
2015/09/17 17:30:03 rendered test template: deprovisionServiceInstance
2015/09/17 17:30:04 rendered test template: serviceUnbind
2015/09/17 17:30:04 rendered test template: catalog
/Users/mohamed/Documents/git/swagger-bosh/src/github.com/maximilien/cf-swagger

 Formatting packages...

Running TCK

You should run the tests against a service broker (we used Go Service Broker), do this with: $ ./bin/run_service_broker_test in your cloned repository.

The end of the output should be similar to:

$ ./bin/run_service_broker_test

...

Tck Compliance v2.6: 100.00 %!
(MISSING)Cause(s) of the failure

Tck Compliance v2.5: 100.00 %!
(MISSING)PASS | FOCUSED

Ginkgo ran 1 suite in 2m31.720074275s
Test Suite Passed

You can modify the go_service_broker code to make it non compliant with v2.6 for testing purpose (making app_id required in bind method for example). You should build the broker again and restart it. Running the same test again will give the following output:

$ ./bin/run_service_broker_test

...

Tck Compliance v2.6: 97.14 %!
(MISSING)Cause(s) of the failure
#serviceBind when service...

Tck Compliance v2.5: 100.00 %!
(MISSING)PASS | FOCUSED

Ginkgo ran 1 suite in 1m31.720074275s
Test Suite Failed

In order to quickly have the test pass, you can start by focusing on createService test, then bind service test. Other parts are being enhanced.

Troubleshooting / FAQs

None for now. Submit questions/comments as issues and we will update here

Filing Bugs

For simple bugs (eg: text formatting, help messages, etc), please provide

• the command options you ran
• what occurred
• what you expected to occur

For panics and other crashes, please provide

• the command you ran
• the stack trace generated (if any)
• any other relevant information

Cloning the repository

1. Install Go
2. Clone (Forking beforehand for development).
3. Ensure your $GOPATH is set correctly

Building

1. Run ./bin/build
2. The binary will be built into the ./out directory

Optionally, you can use bin/run to compile and run the executable in one step.

Developing

1. Run go get golang.org/x/tools/cmd/vet
2. Run go get github.com/xxx ... to install test dependencies (as you see errors)
3. Write a Ginkgo test
4. Run bin/test and watch the test fail
5. Make the test pass
6. Submit a pull request

Contributing

• We gratefully acknowledge and thank the current contributors
• We welcome any and all contributions as Pull Requests (PR)
• We also welcome issues and bug report and new feature request. We will address as time permits
• Follow the steps above in Developing to get your system setup correctly
• Please make sure your PR is passing Travis before submitting
• Feel free to email me or the current collaborators if you have additional questions about contributions
• Before submitting your first PR, please read and follow steps in CONTRIBUTING.md

Managing dependencies

• All dependencies managed via Godep. See Godeps/_workspace directory on master

Short godep Guide

• If you ever import a new package foo/bar (after you go get foo/bar, so that foo/bar is in $GOPATH), you can type godep save ./... to add it to the Godeps directory.
• To restore dependencies from the Godeps directory, simply use godep restore. restore is the opposite of save.
• If you ever remove a dependency or a link becomes deprecated, the easiest way is probably to remove your entire Godeps directory and run godep save ./... again, after making sure all your dependencies are in your $GOPATH. Don't manually edit Godeps.json!
• To update an existing dependency, you can use godep update foo/bar or godep update foo/... (where ... is a wildcard)
• The godep project readme is a pretty good resource: https://github.com/tools/godep

Current conventions

• Basic Go conventions
• Strict TDD for any code added or changed
• Go fakes when needing to mock objects

(*) these items are in the works, we will remove the * once they are available