Tutorials

These tutorials teach codescan by spec concept, not annotation by annotation. Each page takes one thing you want in your OpenAPI document — a model definition, a route, a validated field — and shows the Go annotation that produces it next to the resulting JSON, side by side.

Every Go snippet on these pages comes from the test-covered docs/examples module, and every JSON pane is a golden file a test regenerates — so the examples cannot drift from what the scanner actually emits.

Reading the panes

The example panes put the annotation in on the left and the spec concept out on the right:

// Pet is a single pet in the store.
//
// swagger:model Pet
type Pet struct {
	// The id of the pet.
	//
	// required: true
	// minimum: 1
	ID int64 `json:"id"`

	// The name of the pet.
	//
	// required: true
	// min length: 1
	Name string `json:"name"`

	// The tags associated with this pet.
	Tags []string `json:"tags,omitempty"`
}

{
  "consumes": [
    "application/json"
  ],
  "produces": [
    "application/json"
  ],
  "schemes": [
    "https"
  ],
  "swagger": "2.0",
  "info": {
    "description": "A tiny pet store, used to demonstrate codescan annotations: the package\ncomment is a `swagger:meta` block carrying the top-level metadata of the\ngenerated specification (title, description, version, base path, …).",
    "title": "Petstore API",
    "version": "1.0.0"
  },
  "basePath": "/v1",
  "paths": {
    "/pets": {
      "get": {
        "tags": [
          "pets"
        ],
        "summary": "Lists all the pets in the store.",
        "operationId": "listPets",
        "responses": {
          "200": {
            "$ref": "#/responses/petsResponse"
          }
        }
      }
    }
  },
  "definitions": {
    "Pet": {
      "type": "object",
      "title": "Pet is a single pet in the store.",
      "required": [
        "id",
        "name"
      ],
      "properties": {
        "id": {
          "description": "The id of the pet.",
          "type": "integer",
          "format": "int64",
          "minimum": 1,
          "x-go-name": "ID"
        },
        "name": {
          "description": "The name of the pet.",
          "type": "string",
          "minLength": 1,
          "x-go-name": "Name"
        },
        "tags": {
          "description": "The tags associated with this pet.",
          "type": "array",
          "items": {
            "type": "string"
          },
          "x-go-name": "Tags"
        }
      },
      "x-go-package": "github.com/go-openapi/codescan/docs/examples/petstore"
    }
  },
  "responses": {
    "petsResponse": {
      "description": "petsResponse is the list of pets returned by listPets.",
      "schema": {
        "type": "array",
        "items": {
          "$ref": "#/definitions/Pet"
        }
      }
    }
  }
}

The concepts

• Model definitions

  Turn Go types into spec definitions — structs, string formats, enums, allOf composition, and the per-type overrides.
• Enumerations

  Publish a Go const block as a spec enum — any constant expression, the type and format taken from the declaration, and the same members inline on parameters and headers.
• Maps & free-form objects

  How Go maps render as objects, which key types survive, and how to control a schema’s open/closed/typed extra keys with additionalProperties and patternProperties.
• Polymorphic models

  Model a Swagger 2.0 type hierarchy — a base type with a discriminator and subtypes that compose it with swagger:allOf.
• Routes & operations

  Publish paths and operations — swagger:route and swagger:operation — with their parameters and responses.
• Sharing parameters & responses

  Declare a parameter or response once and reuse it across operations through the spec-level shared namespace, with the wildcard swagger:parameters and swagger:response forms.
• Validations

  Drive JSON-Schema validations from field doc comments — numeric ranges, length and array bounds, patterns, formats, and enums — and understand the reduced surface on parameters and headers.
• Examples & defaults

  Attach example values and defaults to properties — and understand the narrow swagger:default hint.
• Other type decorators

  Mark a property read-only, and an operation deprecated.
• Document metadata

  Set the top-level spec fields — title, version, host, basePath, schemes, consumes/produces, license and contact — from the package doc comment.
• Security

  Declare security schemes in swagger:meta, require them per route, or keep security out of your code entirely and overlay it onto the spec.
• Putting it together

  The smallest end-to-end use of codescan: annotate a package, scan it, and get back a Swagger 2.0 document.

When you want the exhaustive rule rather than an example, every page links into the Maintainers reference; the Annotation index maps every annotation to both.