📖 3 min read (~ 700 words).

Document metadata

A single swagger:meta block on a package doc comment carries the document’s top-level metadata: its info (title, description, version, license, contact), the host and basePath, the default schemes, and consumes/produces. The pane pairs the annotated package with the document it produces, from the test-covered docs/examples/concepts/meta package.

swagger:meta

The block lives in the package doc comment. The title comes from the first line with the Package <name> prefix stripped; the following paragraph becomes the description. The indented Key: value lines and list blocks populate the rest — License: and Contact: parse into structured objects, and an ExternalDocs: block (description + url) populates the spec’s top-level externalDocs. An InfoExtensions: block adds x-* vendor extensions to the info object — this is where an x-logo (rendered by ReDoc / Swagger UI) goes.

Package doc comment
// Package meta Pet Store.
//
// A small API that demonstrates the document-level swagger:meta block: the
// package doc comment carries the spec's top-level metadata.
//
//	Schemes: https
//	Host: api.example.com
//	BasePath: /v1
//	Version: 1.2.0
//	License: Apache 2.0 https://www.apache.org/licenses/LICENSE-2.0.html
//	Contact: API Team <api@example.com> https://example.com/support
//
//	Consumes:
//	  - application/json
//
//	Produces:
//	  - application/json
//
//	ExternalDocs:
//	  description: Full API guide
//	  url: https://example.com/docs
//
//	Tags:
//	- name: pets
//	  description: Everything about your Pets
//	  externalDocs:
//	    description: Find out more
//	    url: https://example.com/docs/pets
//	- name: store
//	  description: Access to Petstore orders
//	  x-display-name: Store
//
//	SecurityDefinitions:
//	  basic_auth:
//	    type: basic
//	  api_key:
//	    type: apiKey
//	    in: header
//	    name: X-API-Key
//
//	Security:
//	  basic_auth:
//
//	InfoExtensions:
//	  x-logo:
//	    url: https://example.com/logo.png
//	    altText: Example
//
// swagger:meta
package meta

Full source: docs/examples/concepts/meta/doc.go

the document
{
  "consumes": [
    "application/json"
  ],
  "produces": [
    "application/json"
  ],
  "schemes": [
    "https"
  ],
  "swagger": "2.0",
  "info": {
    "description": "A small API that demonstrates the document-level swagger:meta block: the\npackage doc comment carries the spec's top-level metadata.",
    "title": "Pet Store.",
    "contact": {
      "name": "API Team",
      "url": "https://example.com/support",
      "email": "api@example.com"
    },
    "license": {
      "name": "Apache 2.0",
      "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
    },
    "version": "1.2.0",
    "x-logo": {
      "altText": "Example",
      "url": "https://example.com/logo.png"
    }
  },
  "host": "api.example.com",
  "basePath": "/v1",
  "paths": {},
  "securityDefinitions": {
    "api_key": {
      "type": "apiKey",
      "name": "X-API-Key",
      "in": "header"
    },
    "basic_auth": {
      "type": "basic"
    }
  },
  "security": [
    {
      "basic_auth": []
    }
  ],
  "tags": [
    {
      "description": "Everything about your Pets",
      "name": "pets",
      "externalDocs": {
        "description": "Find out more",
        "url": "https://example.com/docs/pets"
      }
    },
    {
      "description": "Access to Petstore orders",
      "name": "store",
      "x-display-name": "Store"
    }
  ],
  "externalDocs": {
    "description": "Full API guide",
    "url": "https://example.com/docs"
  }
}

Full source: docs/examples/concepts/meta/testdata/meta.json

Tags

A Tags: block declares the spec’s top-level tags — a YAML sequence of tag objects, each with a name, an optional description, a nested externalDocs, and any x-* vendor extensions. This is how you attach per-tag descriptions to the tags your routes reference (above, pets and store).

For the full meta keyword surface (security definitions, external docs, extensions, terms of service), see the swagger:meta reference and the meta keywords.

Security

The meta block above also declares SecurityDefinitions: (the auth schemes) and a Security: default — authentication is declared, not hand-rolled. Declaring schemes, requiring them per route, and overlaying security from outside the code have their own walkthrough: Security.

A build-time version

Version: is a static literal in source — there is no Options field for it. To stamp a version computed at build time, drive codescan as a library and set it on the returned document after Run:

doc, _ := codescan.Run(opts)
doc.Info.Version = buildVersion // e.g. injected via -ldflags "-X main.buildVersion=..."

Alternatively, overlay a base document that already carries the version with Options.InputSpec (see Overlaying a spec).

What’s next