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 what you see published here has been tested.

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

• Scan a package

  The smallest end-to-end use of codescan: annotate a package, scan it, and get back a Swagger 2.0 document.
• 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.