Overlaying a spec

Options.InputSpec seeds the scan with an existing *spec.Swagger: codescan merges what it discovers on top of it rather than starting from a blank document. Use it to keep hand-authored top-level metadata or a hand-written definition, or to compose a spec across several scans.

The scanned package contributes one model:

// Widget is discovered by the scan and merged onto the input spec.
//
// swagger:model
type Widget struct {
	// ID identifies the widget.
	ID string `json:"id"`
}

Full source: docs/examples/shaping/overlay/overlay.go

Given a base document with metadata and a hand-authored Health definition, the scan preserves all of it and adds the discovered Widget:

InputSpec (base)

{
  "swagger": "2.0",
  "info": {
    "title": "Inventory API",
    "version": "1.0.0"
  },
  "host": "api.example.com",
  "basePath": "/v1",
  "paths": null,
  "definitions": {
    "Health": {
      "type": "object",
      "properties": {
        "ok": {
          "type": "boolean"
        }
      }
    }
  }
}

Full source: docs/examples/shaping/overlay/testdata/base.json

After the scan

{
  "swagger": "2.0",
  "info": {
    "title": "Inventory API",
    "version": "1.0.0"
  },
  "host": "api.example.com",
  "basePath": "/v1",
  "paths": {},
  "definitions": {
    "Health": {
      "type": "object",
      "properties": {
        "ok": {
          "type": "boolean"
        }
      }
    },
    "Widget": {
      "type": "object",
      "title": "Widget is discovered by the scan and merged onto the input spec.",
      "properties": {
        "id": {
          "description": "ID identifies the widget.",
          "type": "string",
          "x-go-name": "ID"
        }
      },
      "x-go-package": "github.com/go-openapi/codescan/docs/examples/shaping/overlay"
    }
  }
}

Full source: docs/examples/shaping/overlay/testdata/merged.json

var base spec.Swagger
_ = json.Unmarshal(baseSpecJSON, &base)

doc, _ := codescan.Run(&codescan.Options{
    Packages:   []string{"./..."},
    ScanModels: true,
    InputSpec:  &base,
})

The document’s info, host, basePath and the hand-authored Health definition survive untouched; only the discovered definitions are added.