go-swagger

README

swagger cmd

This command runs the go test bench with swagger.

generated code

In addition to the code that go-swagger generates, we have a regen command which generates additional code and swagger.yml. This is done to retain a single source of truth across all frameworks and to minimize the complexity of future enhancements. The intent is to

• retain a single source of truth across all frameworks
• decouple frameworks and vulnerabilities, such that addition of either requires minimal or no changes to existing code.

direct editing of swagger.yml

Warning Only use this for experiments, not for PRs to Contrast-Security-OSS/go-test-bench. PRs should update the generator or its inputs.

Do not run ./regen if you have edits to swagger.yml (or ../../pkg/serveswagger/generatedInit.go) that you wish to keep, as it will overwrite both files. Instead, run swagger directly:

cd cmd/go-swagger/restapi
swagger generate server --target ../../go-swagger --name SwaggerBench --spec ../swagger.yml --principal 'interface{}' --exclude-main

Note Swagger itself will still overwrite any changes to the .go files that are marked do not edit and that were generated by swagger - any changes to those files would need to wait unti after swagger ran.

updating spec and code with regen (preferred method)

Additions, deletions, or changes to any common.Route will require use of ./regen. Doing so will overwrite

• swagger.yml
• swagger's generated go code (cmd/go-swagger/restapi/...)
• its own generated go code (pkg/serveswagger/generatedInit.go)

Run regen via go generate ./.... Alternately, cd cmd/go-swagger/restapi; go run ../regen/regen.go.

what does regen do?

in order:

• loads route data
• generates swagger.yml
  • standard swagger spec file
  • derived from template under regen/data
• runs swagger to re-generate code
• generates generatedInit.go
  • boilerplate, derived from template under regen/data
  • contains one function, generatedInit(), which is called from serveswagger.Setup()
  • ties our one-size-fits-all route handler serveswagger.RouteHandler() to each swagger endpoint