allow multiple Swagger documents (no breaking changes)

cmd/swag/main.go

@@ -23,6 +23,7 @@ const (
  parseInternalFlag = "parseInternal"
  generatedTimeFlag = "generatedTime"
  parseDepthFlag = "parseDepth"
+ instanceNameFlag = "instanceName"
 )
 
 var initFlags = []cli.Flag{
@@ -87,6 +88,11 @@ var initFlags = []cli.Flag{
  Value: 100,
  Usage: "Dependency parse depth",
  },
+ &cli.StringFlag{
+ Name: instanceNameFlag,
+ Value: "",
+ Usage: "This parameter can be used to name different swagger document instances. It is optional.",
+ },
 }
 
 func initAction(c *cli.Context) error {
@@ -111,6 +117,7 @@ func initAction(c *cli.Context) error {
  GeneratedTime: c.Bool(generatedTimeFlag),
  CodeExampleFilesDir: c.String(codeExampleFilesFlag),
  ParseDepth: c.Int(parseDepthFlag),
+ InstanceName: c.String(instanceNameFlag),
  })
 }
 

gen/gen.go

@@ -74,10 +74,18 @@ type Config struct {
 
  // ParseDepth dependency parse depth
  ParseDepth int
+
+ // InstanceName is used to get distinct names for different swagger documents in the
+ // same project. The default value is "swagger".
+ InstanceName string
 }
 
 // Build builds swagger json file for given searchDir and mainAPIFile. Returns json
 func (g *Gen) Build(config *Config) error {
+ if config.InstanceName == "" {
+ config.InstanceName = swag.Name
+ }
+
  searchDirs := strings.Split(config.SearchDir, ",")
  for _, searchDir := range searchDirs {
  if _, err := os.Stat(searchDir); os.IsNotExist(err) {
@@ -233,6 +241,7 @@ func (g *Gen) writeGoDoc(packageName string, output io.Writer, swagger *spec.Swa
  Title string
  Description string
  Version string
+ InstanceName string
  }{
  Timestamp: time.Now(),
  GeneratedTime: config.GeneratedTime,
@@ -244,6 +253,7 @@ func (g *Gen) writeGoDoc(packageName string, output io.Writer, swagger *spec.Swa
  Title: swagger.Info.Title,
  Description: swagger.Info.Description,
  Version: swagger.Info.Version,
+ InstanceName: config.InstanceName,
  })
  if err != nil {
  return err
@@ -323,6 +333,6 @@ func (s *s) ReadDoc() string {
 }
 
 func init() {
- swag.Register(swag.Name, &s{})
+ swag.Register({{ printf "%q" .InstanceName }}, &s{})
 }
 `

gen/gen_test.go

@@ -8,6 +8,7 @@ import (
  "os/exec"
  "path/filepath"
  "plugin"
+ "strings"
  "testing"
 
  "github.com/go-openapi/spec"
@@ -39,6 +40,53 @@ func TestGen_Build(t *testing.T) {
  }
 }
 
+func TestGen_BuildInstanceName(t *testing.T) {
+ searchDir := "../testdata/simple"
+
+ config := &Config{
+ SearchDir: searchDir,
+ MainAPIFile: "./main.go",
+ OutputDir: "../testdata/simple/docs",
+ PropNamingStrategy: "",
+ }
+ assert.NoError(t, New().Build(config))
+
+ goSourceFile := filepath.Join(config.OutputDir, "docs.go")
+
+ // Validate default registration name
+ expectedCode, err := ioutil.ReadFile(goSourceFile)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if !strings.Contains(string(expectedCode), "swag.Register(\"swagger\", &s{})") {
+ t.Fatal(errors.New("generated go code does not contain the correct default registration sequence"))
+ }
+
+ // Custom name
+ config.InstanceName = "custom"
+ assert.NoError(t, New().Build(config))
+ expectedCode, err = ioutil.ReadFile(goSourceFile)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if !strings.Contains(string(expectedCode), "swag.Register(\"custom\", &s{})") {
+ t.Fatal(errors.New("generated go code does not contain the correct registration sequence"))
+ }
+
+ // cleanup
+ expectedFiles := []string{
+ filepath.Join(config.OutputDir, "docs.go"),
+ filepath.Join(config.OutputDir, "swagger.json"),
+ filepath.Join(config.OutputDir, "swagger.yaml"),
+ }
+ for _, expectedFile := range expectedFiles {
+ if _, err := os.Stat(expectedFile); os.IsNotExist(err) {
+ t.Fatal(err)
+ }
+ _ = os.Remove(expectedFile)
+ }
+}
+
 func TestGen_BuildSnakecase(t *testing.T) {
  searchDir := "../testdata/simple2"
  config := &Config{

swagger.go

@@ -2,6 +2,7 @@ package swag
 
 import (
  "errors"
+ "fmt"
  "sync"
 )
 
@@ -10,7 +11,7 @@ const Name = "swagger"
 
 var (
  swaggerMu sync.RWMutex
- swag  Swagger
+ swags map[string]Swagger
 )
 
 // Swagger is a interface to read swagger document.
@@ -26,17 +27,35 @@ func Register(name string, swagger Swagger) {
  panic("swagger is nil")
  }
 
- if swag != nil {
+ if swags == nil {
+ swags = make(map[string]Swagger)
+ }
+
+ if _, ok := swags[name]; ok {
  panic("Register called twice for swag: " + name)
  }
- swag = swagger
+ swags[name] = swagger
 }
 
-// ReadDoc reads swagger document.
-func ReadDoc() (string, error) {
- if swag != nil {
- return swag.ReadDoc(), nil
+// ReadDoc reads swagger document. An optional name parameter can be passed to read a specific document.
+// The default name is "swagger".
+func ReadDoc(optionalName ...string) (string, error) {
+ swaggerMu.RLock()
+ defer swaggerMu.RUnlock()
+
+ if swags == nil {
+ return "", errors.New("no swag has yet been registered")
+ }
+
+ name := Name
+ if len(optionalName) != 0 && optionalName[0] != "" {
+ name = optionalName[0]
+ }
+
+ swag, ok := swags[name]
+ if !ok {
+ return "", fmt.Errorf("no swag named \"%s\" was registered", name)
  }
 
- return "", errors.New("not yet registered swag")
+ return swag.ReadDoc(), nil
 }

swagger_test.go

@@ -162,12 +162,36 @@ func TestRegister(t *testing.T) {
  assert.Equal(t, doc, d)
 }
 
+func TestRegisterByName(t *testing.T) {
+ setup()
+ Register("another_name", &s{})
+ d, _ := ReadDoc("another_name")
+ assert.Equal(t, doc, d)
+}
+
+func TestRegisterMultiple(t *testing.T) {
+ setup()
+ Register(Name, &s{})
+ Register("another_name", &s{})
+ d1, _ := ReadDoc(Name)
+ d2, _ := ReadDoc("another_name")
+ assert.Equal(t, doc, d1)
+ assert.Equal(t, doc, d2)
+}
+
 func TestReadDocBeforeRegistered(t *testing.T) {
  setup()
  _, err := ReadDoc()
  assert.Error(t, err)
 }
 
+func TestReadDocWithInvalidName(t *testing.T) {
+ setup()
+ Register(Name, &s{})
+ _, err := ReadDoc("invalid")
+ assert.Error(t, err)
+}
+
 func TestNilRegister(t *testing.T) {
  setup()
  var swagger Swagger
@@ -185,5 +209,5 @@ func TestCalledTwicelRegister(t *testing.T) {
 }
 
 func setup() {
- swag = nil
+ swags = nil
 }