📖 3 min read (~ 600 words).

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:

Annotated Go
// 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"`
}

Full source: docs/examples/petstore/pet.go

Generated spec
{
  "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"
        }
      }
    }
  }
}

Full source: docs/examples/basic/testdata/swagger.json

The concepts

  • Turn Go types into spec definitions — structs, string formats, enums, allOf composition, and the per-type overrides.
  • Publish paths and operations — swagger:route and swagger:operation — with their parameters and responses.
  • 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.
  • Attach example values and defaults to properties — and understand the narrow swagger:default hint.
  • Set the top-level spec fields — title, version, host, basePath, schemes, consumes/produces, license and contact — from the package doc comment.
  • 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.