swagger:meta

Usage

// swagger:meta

What it does

Declares the package as the OpenAPI spec container.

The scanner reads the package doc comment for the top-level spec fields: title (via stripPackagePrefix of the doc’s first line), description, license, contact, host, basePath, version, schemes, consumes, produces, securityDefinitions, extensions, and the rest of the meta keyword surface.

Where it goes

On the package doc comment. No arguments — a bare annotation.

Grammar (EBNF)

MetaBlock = ANN_META , [ Title ] , [ Description ] , MetaBody ;

The body is a MetaBody of single-line MetaKeywords (version, host, basePath, license, contact, schemes) and MetaRawBlocks (consumes, produces, security, securityDefinitions, tos). See grammar §meta-family.

Supported keywords

All meta single-line keywords (schemes, version, host, basePath, license, contact) plus the meta-scope body keywords (consumes, produces, security, securityDefinitions, extensions, infoExtensions, tos, externalDocs, tags). A Tags: block declares the spec’s top-level tags (name, description, nested externalDocs, x-* extensions per tag).

Example

Annotated Go

// 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

Generated spec

{
  "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

Full example. fixtures/goparsing/spec/api.go.