README

codescan

A Go source code scanner that produces Swagger 2.0 (OpenAPI 2.0) specifications from annotated Go source files.

Supports Go modules (since go1.11).

Announcements

• 2025-04-19: large package layout reshuffle
  • the entire project is being refactored to restore a reasonable level of maintainability
  • the only exposed API is Run() and Options.

Status

API is stable.

Import this library in your project

go get github.com/go-openapi/codescan

Basic usage

import (
  "github.com/go-openapi/codescan"
)

swaggerSpec, err := codescan.Run(&codescan.Options{
  Packages: []string{"./..."},
})

See getting started for a worked example.

Change log

See https://github.com/go-openapi/codescan/releases.

Licensing

This library ships under the Apache-2.0 license.

See the license NOTICE, which recalls the licensing terms of all the pieces of software on top of which it has been built.

Other documentation

• All-time contributors
• Contributing guidelines
• Maintainers documentation
• Code style

LICENSE

                                 Apache License
                           Version 2.0, January 2004
                        http://www.apache.org/licenses/

   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION

   1. Definitions.

      "License" shall mean the terms and conditions for use, reproduction,
      and distribution as defined by Sections 1 through 9 of this document.

      "Licensor" shall mean the copyright owner or entity authorized by
      the copyright owner that is granting the License.

      "Legal Entity" shall mean the union of the acting entity and all
      other entities that control, are controlled by, or are under common
      control with that entity. For the purposes of this definition,
      "control" means (i) the power, direct or indirect, to cause the
      direction or management of such entity, whether by contract or
      otherwise, or (ii) ownership of fifty percent (50%) or more of the
      outstanding shares, or (iii) beneficial ownership of such entity.

      "You" (or "Your") shall mean an individual or Legal Entity
      exercising permissions granted by this License.

      "Source" form shall mean the preferred form for making modifications,
      including but not limited to software source code, documentation
      source, and configuration files.

      "Object" form shall mean any form resulting from mechanical
      transformation or translation of a Source form, including but
      not limited to compiled object code, generated documentation,
      and conversions to other media types.

      "Work" shall mean the work of authorship, whether in Source or
      Object form, made available under the License, as indicated by a
      copyright notice that is included in or attached to the work
      (an example is provided in the Appendix below).

      "Derivative Works" shall mean any work, whether in Source or Object
      form, that is based on (or derived from) the Work and for which the
      editorial revisions, annotations, elaborations, or other modifications
      represent, as a whole, an original work of authorship. For the purposes
      of this License, Derivative Works shall not include works that remain
      separable from, or merely link (or bind by name) to the interfaces of,
      the Work and Derivative Works thereof.

      "Contribution" shall mean any work of authorship, including
      the original version of the Work and any modifications or additions
      to that Work or Derivative Works thereof, that is intentionally
      submitted to Licensor for inclusion in the Work by the copyright owner
      or by an individual or Legal Entity authorized to submit on behalf of
      the copyright owner. For the purposes of this definition, "submitted"
      means any form of electronic, verbal, or written communication sent
      to the Licensor or its representatives, including but not limited to
      communication on electronic mailing lists, source code control systems,
      and issue tracking systems that are managed by, or on behalf of, the
      Licensor for the purpose of discussing and improving the Work, but
      excluding communication that is conspicuously marked or otherwise
      designated in writing by the copyright owner as "Not a Contribution."

      "Contributor" shall mean Licensor and any individual or Legal Entity
      on behalf of whom a Contribution has been received by Licensor and
      subsequently incorporated within the Work.

   2. Grant of Copyright License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      copyright license to reproduce, prepare Derivative Works of,
      publicly display, publicly perform, sublicense, and distribute the
      Work and such Derivative Works in Source or Object form.

   3. Grant of Patent License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      (except as stated in this section) patent license to make, have made,
      use, offer to sell, sell, import, and otherwise transfer the Work,
      where such license applies only to those patent claims licensable
      by such Contributor that are necessarily infringed by their
      Contribution(s) alone or by combination of their Contribution(s)
      with the Work to which such Contribution(s) was submitted. If You
      institute patent litigation against any entity (including a
      cross-claim or counterclaim in a lawsuit) alleging that the Work
      or a Contribution incorporated within the Work constitutes direct
      or contributory patent infringement, then any patent licenses
      granted to You under this License for that Work shall terminate
      as of the date such litigation is filed.

   4. Redistribution. You may reproduce and distribute copies of the
      Work or Derivative Works thereof in any medium, with or without
      modifications, and in Source or Object form, provided that You
      meet the following conditions:

      (a) You must give any other recipients of the Work or
          Derivative Works a copy of this License; and

      (b) You must cause any modified files to carry prominent notices
          stating that You changed the files; and

      (c) You must retain, in the Source form of any Derivative Works
          that You distribute, all copyright, patent, trademark, and
          attribution notices from the Source form of the Work,
          excluding those notices that do not pertain to any part of
          the Derivative Works; and

      (d) If the Work includes a "NOTICE" text file as part of its
          distribution, then any Derivative Works that You distribute must
          include a readable copy of the attribution notices contained
          within such NOTICE file, excluding those notices that do not
          pertain to any part of the Derivative Works, in at least one
          of the following places: within a NOTICE text file distributed
          as part of the Derivative Works; within the Source form or
          documentation, if provided along with the Derivative Works; or,
          within a display generated by the Derivative Works, if and
          wherever such third-party notices normally appear. The contents
          of the NOTICE file are for informational purposes only and
          do not modify the License. You may add Your own attribution
          notices within Derivative Works that You distribute, alongside
          or as an addendum to the NOTICE text from the Work, provided
          that such additional attribution notices cannot be construed
          as modifying the License.

      You may add Your own copyright statement to Your modifications and
      may provide additional or different license terms and conditions
      for use, reproduction, or distribution of Your modifications, or
      for any such Derivative Works as a whole, provided Your use,
      reproduction, and distribution of the Work otherwise complies with
      the conditions stated in this License.

   5. Submission of Contributions. Unless You explicitly state otherwise,
      any Contribution intentionally submitted for inclusion in the Work
      by You to the Licensor shall be under the terms and conditions of
      this License, without any additional terms or conditions.
      Notwithstanding the above, nothing herein shall supersede or modify
      the terms of any separate license agreement you may have executed
      with Licensor regarding such Contributions.

   6. Trademarks. This License does not grant permission to use the trade
      names, trademarks, service marks, or product names of the Licensor,
      except as required for reasonable and customary use in describing the
      origin of the Work and reproducing the content of the NOTICE file.

   7. Disclaimer of Warranty. Unless required by applicable law or
      agreed to in writing, Licensor provides the Work (and each
      Contributor provides its Contributions) on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
      implied, including, without limitation, any warranties or conditions
      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
      PARTICULAR PURPOSE. You are solely responsible for determining the
      appropriateness of using or redistributing the Work and assume any
      risks associated with Your exercise of permissions under this License.

   8. Limitation of Liability. In no event and under no legal theory,
      whether in tort (including negligence), contract, or otherwise,
      unless required by applicable law (such as deliberate and grossly
      negligent acts) or agreed to in writing, shall any Contributor be
      liable to You for damages, including any direct, indirect, special,
      incidental, or consequential damages of any character arising as a
      result of this License or out of the use or inability to use the
      Work (including but not limited to damages for loss of goodwill,
      work stoppage, computer failure or malfunction, or any and all
      other commercial damages or losses), even if such Contributor
      has been advised of the possibility of such damages.

   9. Accepting Warranty or Additional Liability. While redistributing
      the Work or Derivative Works thereof, You may choose to offer,
      and charge a fee for, acceptance of support, warranty, indemnity,
      or other liability obligations and/or rights consistent with this
      License. However, in accepting such obligations, You may act only
      on Your own behalf and on Your sole responsibility, not on behalf
      of any other Contributor, and only if You agree to indemnify,
      defend, and hold each Contributor harmless for any liability
      incurred by, or claims asserted against, such Contributor by reason
      of your accepting any such warranty or additional liability.

   END OF TERMS AND CONDITIONS

   APPENDIX: How to apply the Apache License to your work.

      To apply the Apache License to your work, attach the following
      boilerplate notice, with the fields enclosed by brackets "[]"
      replaced with your own identifying information. (Don't include
      the brackets!)  The text should be enclosed in the appropriate
      comment syntax for the file format. We also recommend that a
      file or class name and description of purpose be included on the
      same "printed page" as the copyright notice for easier
      identification within third-party archives.

   Copyright [yyyy] [name of copyright owner]

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.

Usage as a library

The most direct way to use codescan is to import it and call Run from your own Go program — a generator, a go:generate step, or a test that keeps your spec in sync with the source.

Annotate your source

Annotations are special comments following the go-swagger convention (swagger:meta, swagger:route, swagger:model, swagger:parameters, swagger:response, …).

A package-level swagger:meta block carries the top-level metadata of the spec:

// Package petstore Petstore API
//
// A tiny pet store, used to demonstrate codescan annotations: the package
// comment is a `swagger:meta` block carrying the top-level metadata of the
// generated specification (title, description, version, base path, …).
//
//	Schemes: https
//	Version: 1.0.0
//	BasePath: /v1
//
//	Consumes:
//	- application/json
//
//	Produces:
//	- application/json
//
// swagger:meta

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

A swagger:model annotation turns a Go struct into a definition; field-level comments become validations and descriptions:

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

Run the scanner

Point codescan at the package(s) to scan. Patterns are relative go list-style patterns, resolved against WorkDir:

opts := &codescan.Options{
	WorkDir:    workDir,                // module root to resolve patterns from
	Packages:   []string{"./petstore"}, // relative package pattern
	ScanModels: true,                   // also emit definitions for swagger:model types
}

doc, err := codescan.Run(opts)
if err != nil {
	return nil, err
}

Full source: docs/examples/basic/scan.go

The returned *spec.Swagger is the standard github.com/go-openapi/spec document — marshal it to JSON or YAML, feed it to a validator, or merge it onto an existing spec via Options.InputSpec.

Options worth knowing

See the godoc for the full list.

Next

• Tutorials — the worked, by-concept version of the above, each with the spec it produces.
• Annotation index — every annotation at a glance, linked to its example and its full reference.
• Maintainers reference — the complete annotation vocabulary, keywords, and grammar.

Model definitions

A definitions entry is the most common thing you ask codescan to produce. This page walks the annotations that create and shape one, from the plain swagger:model struct to the per-type overrides. Each pane pairs the annotated Go (left) with the exact fragment the scanner emits (right) — both come from the test-covered docs/examples/concepts/models package.

For the exhaustive rule on any annotation below, follow its link to the Maintainers reference.

swagger:model

swagger:model publishes a Go struct as a definition. Field doc comments become property descriptions; json tags drive the property names; the Go type drives the JSON-Schema type / format.

// Pet is a single pet in the store.
//
// swagger:model
type Pet struct {
	// ID is the unique identifier.
	ID int64 `json:"id"`

	// Name is the pet's display name.
	Name string `json:"name"`

	// Tags categorise the pet.
	Tags []string `json:"tags,omitempty"`
}

{
  "type": "object",
  "title": "Pet is a single pet in the store.",
  "properties": {
    "id": {
      "description": "ID is the unique identifier.",
      "type": "integer",
      "format": "int64",
      "x-go-name": "ID"
    },
    "name": {
      "description": "Name is the pet's display name.",
      "type": "string",
      "x-go-name": "Name"
    },
    "tags": {
      "description": "Tags categorise the pet.",
      "type": "array",
      "items": {
        "type": "string"
      },
      "x-go-name": "Tags"
    }
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/models"
}

swagger:strfmt

swagger:strfmt <name> marks a named string type as a custom format. The type does not become its own definition — instead, every field typed by it renders as {type: string, format: <name>}.

// MAC is a hardware address rendered as a colon-separated hex string.
//
// swagger:strfmt mac
type MAC string

func (m MAC) MarshalText() ([]byte, error)  { return []byte(m), nil }
func (m *MAC) UnmarshalText(b []byte) error { *m = MAC(b); return nil }

// Device exposes a strfmt-typed field: wherever MAC appears it renders inline
// as {type: string, format: mac}.
//
// swagger:model
type Device struct {
	// Addr is the hardware address.
	Addr MAC `json:"addr"`
}

{
  "description": "Device exposes a strfmt-typed field: wherever MAC appears it renders inline\nas {type: string, format: mac}.",
  "type": "object",
  "properties": {
    "addr": {
      "description": "Addr is the hardware address.",
      "type": "string",
      "format": "mac",
      "x-go-name": "Addr"
    }
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/models"
}

swagger:enum

swagger:enum <name> collects the type’s const values. When a model field references the type, the property carries the enum array and an x-go-enum-desc extension built from the per-value doc comments. (The enum type is reachable, and so emitted, only because a model field points at it.)

// Priority is the urgency level on a task.
//
// swagger:enum Priority
type Priority string

const (
	// PriorityLow is for tasks that can wait.
	PriorityLow Priority = "low"
	// PriorityMedium is the default.
	PriorityMedium Priority = "medium"
	// PriorityHigh is for tasks that must run soon.
	PriorityHigh Priority = "high"
)

// Task is a unit of work carrying an enum-typed field. Referencing Priority
// from a model is what makes the enum reachable, and so emitted.
//
// swagger:model
type Task struct {
	// Priority is the task's urgency.
	Priority Priority `json:"priority"`
}

{
  "description": "Task is a unit of work carrying an enum-typed field. Referencing Priority\nfrom a model is what makes the enum reachable, and so emitted.",
  "type": "object",
  "properties": {
    "priority": {
      "description": "Priority is the task's urgency.\nlow PriorityLow is for tasks that can wait.\nmedium PriorityMedium is the default.\nhigh PriorityHigh is for tasks that must run soon.",
      "type": "string",
      "enum": [
        "low",
        "medium",
        "high"
      ],
      "x-go-enum-desc": "low PriorityLow is for tasks that can wait.\nmedium PriorityMedium is the default.\nhigh PriorityHigh is for tasks that must run soon.",
      "x-go-name": "Priority"
    }
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/models"
}

swagger:allOf

Embedding base types under swagger:allOf composes a schema. Each embedded base becomes a $ref arm of the allOf; the struct’s own (non-embedded) fields form a final inline arm. That last arm is inline rather than a $ref because those fields are new to this type — they belong to no existing definition to point at. Here Dog embeds two bases (Animal, Tagged) and adds breed, producing three arms: two $refs and one inline object.

// Animal is one abstract base.
//
// swagger:model
type Animal struct {
	// Kind discriminates the animal.
	Kind string `json:"kind"`
}

// Tagged is a second reusable base.
//
// swagger:model
type Tagged struct {
	// Tags label the resource.
	Tags []string `json:"tags"`
}

// Dog composes two base models plus its own fields: each embedded base becomes
// a $ref arm of the allOf, and the struct's own (non-embedded) fields — which
// are new and cannot be a $ref — form the final inline arm.
//
// swagger:model
type Dog struct {
	// swagger:allOf
	Animal

	// swagger:allOf
	Tagged

	// Breed is the dog's breed.
	Breed string `json:"breed"`
}

{
  "description": "Dog composes two base models plus its own fields: each embedded base becomes\na $ref arm of the allOf, and the struct's own (non-embedded) fields — which\nare new and cannot be a $ref — form the final inline arm.",
  "allOf": [
    {
      "$ref": "#/definitions/Animal"
    },
    {
      "$ref": "#/definitions/Tagged"
    },
    {
      "type": "object",
      "properties": {
        "breed": {
          "description": "Breed is the dog's breed.",
          "type": "string",
          "x-go-name": "Breed"
        }
      }
    }
  ],
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/models"
}

swagger:type

swagger:type <type> overrides the type codescan would infer. Here a [16]byte field is published as a string.

// ULID is a 128-bit identifier stored as bytes but rendered as a string.
//
// swagger:type string
type ULID [16]byte

// Token carries a field whose inferred type is overridden, inline.
//
// swagger:model
type Token struct {
	// ID renders as a string despite its [16]byte Go type.
	ID ULID `json:"id"`
}

{
  "type": "object",
  "title": "Token carries a field whose inferred type is overridden, inline.",
  "properties": {
    "id": {
      "description": "ID renders as a string despite its [16]byte Go type.",
      "type": "string",
      "x-go-name": "ID"
    }
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/models"
}

The accepted values are the scalar Swagger types — string, integer, number, boolean, object (plus the Go builtin names codescan resolves). array and file are not accepted here; an unrecognized value leaves the field on its underlying Go type.

swagger:name

A model defined as an interface publishes one property per nullary method. By default the property name is the camelCased method name — so Maker() already becomes maker with no annotation. swagger:name <name> is the override for when that default is not what you want (interface methods cannot carry a json tag). Here StructType() would default to structType; the annotation publishes it as jsonClass instead.

// Car is exposed as a schema via its method set. Interface methods cannot carry
// a json tag, so by default each property takes the camelCased method name;
// swagger:name overrides that where the default is not what you want.
//
// swagger:model
type Car interface {
	// Maker is the manufacturer. With no override the property is the
	// camelCased method name, "maker".
	Maker() string

	// StructType is the polymorphic class. Without the override the property
	// would be "structType"; swagger:name publishes it as "jsonClass".
	//
	// swagger:name jsonClass
	StructType() string
}

{
  "description": "Car is exposed as a schema via its method set. Interface methods cannot carry\na json tag, so by default each property takes the camelCased method name;",
  "type": "object",
  "properties": {
    "jsonClass": {
      "description": "StructType is the polymorphic class. Without the override the property\nwould be \"structType\"; swagger:name publishes it as \"jsonClass\".",
      "type": "string",
      "x-go-name": "StructType"
    },
    "maker": {
      "description": "Maker is the manufacturer. With no override the property is the\ncamelCased method name, \"maker\".",
      "type": "string",
      "x-go-name": "Maker"
    }
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/models"
}

swagger:ignore

swagger:ignore drops a declaration from the output. The scanner sees Secret, classifies it, then excludes it — so it never reaches the definitions (a fact the example’s TestIgnoreOmitsType asserts).

// Secret never reaches the spec.
//
// swagger:ignore
type Secret struct {
	// Token is internal.
	Token string `json:"token"`
}

Full source: docs/examples/concepts/models/models.go

What’s next

• Routes & operations — wire these models into paths, parameters and responses.
• Validations — constrain field values with keyword annotations.
• Shaping the output — alias handling, $ref vs inline, nullable pointers and more.

Routes & operations

Routes and operations turn an annotation into an entry in the spec’s paths map, wired to the parameters it accepts and the responses it returns. This page covers the two operation annotations and the companion structs they reference. Each pane pairs the annotated Go (left) with the exact fragment the scanner emits (right), from the test-covered docs/examples/concepts/routes package.

For the exhaustive rule on any annotation below, follow its link to the Maintainers reference; the Parameters: / Responses: body grammars are covered in Sub-languages.

swagger:route

swagger:route <METHOD> <path> [tags] <operationID> declares a path and its operation in one annotation. The body’s responses: block ties status codes to named responses ($ref into the spec’s responses). It lives in a plain comment block — no Go declaration required.

// swagger:route GET /pets pets listPets
//
// Lists pets in the store, optionally filtered by tag.
//
// responses:
//
//	200: petsResponse
//	default: errorResponse

{
  "get": {
    "tags": [
      "pets"
    ],
    "summary": "Lists pets in the store, optionally filtered by tag.",
    "operationId": "listPets",
    "parameters": [
      {
        "type": "string",
        "x-go-name": "Tag",
        "description": "Tag filters pets by tag.",
        "name": "tag",
        "in": "query"
      },
      {
        "maximum": 100,
        "minimum": 1,
        "type": "integer",
        "format": "int32",
        "x-go-name": "Limit",
        "description": "Limit caps the number of results.",
        "name": "limit",
        "in": "query"
      }
    ],
    "responses": {
      "200": {
        "$ref": "#/responses/petsResponse"
      },
      "default": {
        "$ref": "#/responses/errorResponse"
      }
    }
  }
}

swagger:operation

swagger:operation carries the same header but spells the operation out as a YAML document after a --- fence — useful when you want to author the operation object directly (here a path parameter and an inline $ref response schema).

// swagger:operation GET /pets/{id} pets getPet
//
// ---
// summary: Get a pet by ID.
// parameters:
//   - name: id
//     in: path
//     required: true
//     type: integer
//     format: int64
// responses:
//   '200':
//     description: the requested pet
//     schema:
//       $ref: '#/definitions/Pet'
//   default:
//     $ref: '#/responses/errorResponse'

{
  "get": {
    "tags": [
      "pets"
    ],
    "summary": "Get a pet by ID.",
    "operationId": "getPet",
    "parameters": [
      {
        "type": "integer",
        "format": "int64",
        "name": "id",
        "in": "path",
        "required": true
      }
    ],
    "responses": {
      "200": {
        "description": "the requested pet",
        "schema": {
          "$ref": "#/definitions/Pet"
        }
      },
      "default": {
        "$ref": "#/responses/errorResponse"
      }
    }
  }
}

swagger:parameters

swagger:parameters <operationID>… declares a struct whose fields become the parameters of the named operation(s). Field doc comments carry in:, the validations, and the description; the parameters attach to every operation ID listed.

// ListPetsParams is the parameter set for the listPets operation. Each field
// becomes one parameter; the operation IDs after swagger:parameters name the
// operations the set applies to.
//
// swagger:parameters listPets
type ListPetsParams struct {
	// Tag filters pets by tag.
	//
	// in: query
	Tag string `json:"tag"`

	// Limit caps the number of results.
	//
	// in: query
	// minimum: 1
	// maximum: 100
	Limit int32 `json:"limit"`
}

[
  {
    "type": "string",
    "x-go-name": "Tag",
    "description": "Tag filters pets by tag.",
    "name": "tag",
    "in": "query"
  },
  {
    "maximum": 100,
    "minimum": 1,
    "type": "integer",
    "format": "int32",
    "x-go-name": "Limit",
    "description": "Limit caps the number of results.",
    "name": "limit",
    "in": "query"
  }
]

swagger:response

swagger:response <name> declares a struct as a named entry in the spec’s top-level responses. A Body field (or in: body) becomes the response schema; routes reference it by name. Here the body is a []Pet, so the schema is an array of $refs.

// PetsResponse is the list returned by listPets.
//
// swagger:response petsResponse
type PetsResponse struct {
	// in: body
	Body []Pet
}

// ErrorResponse is the default error payload.
//
// swagger:response errorResponse
type ErrorResponse struct {
	// in: body
	Body struct {
		// Message is a human-readable error message.
		Message string `json:"message"`
	}
}

{
  "description": "PetsResponse is the list returned by listPets.",
  "schema": {
    "type": "array",
    "items": {
      "$ref": "#/definitions/Pet"
    }
  }
}

swagger:file

swagger:file on a parameter field marks it as a binary upload — the parameter emits as {type: file}. It belongs on a formData field of a swagger:parameters struct.

// swagger:route POST /pets/{id}/photo pets uploadPetPhoto
//
// responses:
//
//	200: petsResponse

// UploadParams is the multipart upload for the uploadPetPhoto operation.
//
// swagger:parameters uploadPetPhoto
type UploadParams struct {
	// Photo is the image to upload.
	//
	// in: formData
	// swagger:file
	Photo io.ReadCloser `json:"photo"`
}

[
  {
    "type": "file",
    "x-go-name": "Photo",
    "description": "Photo is the image to upload.",
    "name": "photo",
    "in": "formData"
  }
]

What’s next

• Validations — constrain parameter and field values.
• Model definitions — the schemas these operations reference.
• Shaping the output — $ref vs inline, aliases, and the other rendering knobs.

Validations

Validations are keyword-driven: you write keyword: value lines in a field’s doc comment and they become minimum, maxLength, pattern, enum, and the rest of the validation surface on that property. Each pane below pairs the annotated Go (left) with the fragment the scanner emits (right), from the test-covered docs/examples/concepts/validations package.

For the per-keyword reference card — value shapes, aliases, and legal contexts — see Keywords.

On a model field — the full surface

A swagger:model field accepts the full JSON-schema validation vocabulary:

• Numeric — minimum, maximum, multipleOf (on Price).
• Length — min length / max length (on Name).
• Arrays — min items / max items / unique (on Tags).
• Pattern — a regular expression (on SKU).
• Enum — a fixed value set (on Grade).
• Required — required: true lifts the property into the schema’s object-level required array (sku).

// Product is a model whose fields carry the full JSON-schema validation surface.
//
// swagger:model
type Product struct {
	// SKU is the stock code.
	//
	// required: true
	// pattern: ^[A-Z]{3}-[0-9]{4}$
	SKU string `json:"sku"`

	// Price is the price in cents.
	//
	// minimum: 1
	// maximum: 1000000
	// multipleOf: 1
	Price int64 `json:"price"`

	// Name is the display name.
	//
	// min length: 1
	// max length: 120
	Name string `json:"name"`

	// Grade is a quality band.
	//
	// enum: A,B,C
	Grade string `json:"grade"`

	// Tags label the product.
	//
	// min items: 1
	// max items: 10
	// unique: true
	Tags []string `json:"tags"`
}

{
  "type": "object",
  "title": "Product is a model whose fields carry the full JSON-schema validation surface.",
  "required": [
    "sku"
  ],
  "properties": {
    "grade": {
      "description": "Grade is a quality band.",
      "type": "string",
      "enum": [
        "A",
        "B",
        "C"
      ],
      "x-go-name": "Grade"
    },
    "name": {
      "description": "Name is the display name.",
      "type": "string",
      "maxLength": 120,
      "minLength": 1,
      "x-go-name": "Name"
    },
    "price": {
      "description": "Price is the price in cents.",
      "type": "integer",
      "format": "int64",
      "maximum": 1000000,
      "minimum": 1,
      "multipleOf": 1,
      "x-go-name": "Price"
    },
    "sku": {
      "description": "SKU is the stock code.",
      "type": "string",
      "pattern": "^[A-Z]{3}-[0-9]{4}$",
      "x-go-name": "SKU"
    },
    "tags": {
      "description": "Tags label the product.",
      "type": "array",
      "maxItems": 10,
      "minItems": 1,
      "uniqueItems": true,
      "items": {
        "type": "string"
      },
      "x-go-name": "Tags"
    }
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/validations"
}

On parameters — the simple-schema surface

The same numeric and length keywords work on a query parameter; arrays add collectionFormat:

// SearchParams is the simple-schema parameter set for searchProducts. Query
// parameters accept the reduced OAS 2.0 validation surface.
//
// swagger:parameters searchProducts
type SearchParams struct {
	// Q is the search text.
	//
	// in: query
	// min length: 3
	// max length: 50
	Q string `json:"q"`

	// Limit caps the number of results.
	//
	// in: query
	// minimum: 1
	// maximum: 100
	Limit int32 `json:"limit"`

	// Sort lists the sort fields.
	//
	// in: query
	// collection format: csv
	// unique: true
	Sort []string `json:"sort"`
}

[
  {
    "maxLength": 50,
    "minLength": 3,
    "type": "string",
    "x-go-name": "Q",
    "description": "Q is the search text.",
    "name": "q",
    "in": "query"
  },
  {
    "maximum": 100,
    "minimum": 1,
    "type": "integer",
    "format": "int32",
    "x-go-name": "Limit",
    "description": "Limit caps the number of results.",
    "name": "limit",
    "in": "query"
  },
  {
    "uniqueItems": true,
    "type": "array",
    "items": {
      "type": "string"
    },
    "collectionFormat": "csv",
    "x-go-name": "Sort",
    "description": "Sort lists the sort fields.",
    "name": "sort",
    "in": "query"
  }
]

On response headers

A response header is also a simple schema, so it takes the same reduced validation set (here minimum on an integer header). Note headers carry no required flag.

// RateLimited is a response carrying a validated header (a simple schema).
//
// swagger:response rateLimited
type RateLimited struct {
	// XRateRemaining is the remaining request budget.
	//
	// minimum: 0
	XRateRemaining int32 `json:"X-Rate-Remaining"`
}

{
  "description": "RateLimited is a response carrying a validated header (a simple schema).",
  "headers": {
    "X-Rate-Remaining": {
      "minimum": 0,
      "type": "integer",
      "format": "int32",
      "description": "XRateRemaining is the remaining request budget."
    }
  }
}

What’s next

• Examples & defaults — attach example values and defaults.
• Other type decorators — readOnly and deprecated.
• Keyword reference — every keyword, its value shape, and where it is legal.

Examples & defaults

Example values and defaults are documentation that travels with the schema: an example: shows a caller what a value looks like, a default: declares what the field is when the caller omits it. Both are typed to the field — a numeric default on an integer field is a JSON number, not a string. The panes below pair the annotated Go with the fragment the scanner emits, from the test-covered docs/examples/concepts/examples package.

For the exact value shapes these keywords accept, see Keywords.

example

example: <value> attaches an example to the property, coerced to the field’s type — Hello, world! stays a string, 3 becomes a number.

// Greeting carries an example value for documentation.
//
// swagger:model
type Greeting struct {
	// Message is the greeting text.
	//
	// example: Hello, world!
	Message string `json:"message"`

	// Count is how many times to repeat it.
	//
	// example: 3
	Count int32 `json:"count"`
}

{
  "type": "object",
  "title": "Greeting carries an example value for documentation.",
  "properties": {
    "count": {
      "description": "Count is how many times to repeat it.",
      "type": "integer",
      "format": "int32",
      "x-go-name": "Count",
      "example": 3
    },
    "message": {
      "description": "Message is the greeting text.",
      "type": "string",
      "x-go-name": "Message",
      "example": "Hello, world!"
    }
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/examples"
}

default

default: <value> sets the property’s default, again typed to the field — 8080 is a number, false a boolean, auto a string.

// Settings carries default values applied when a field is omitted.
//
// swagger:model
type Settings struct {
	// Port is the listen port.
	//
	// default: 8080
	Port int32 `json:"port"`

	// Mode is the run mode.
	//
	// default: auto
	Mode string `json:"mode"`

	// Verbose toggles verbose logging.
	//
	// default: false
	Verbose bool `json:"verbose"`
}

{
  "type": "object",
  "title": "Settings carries default values applied when a field is omitted.",
  "properties": {
    "mode": {
      "description": "Mode is the run mode.",
      "type": "string",
      "default": "auto",
      "x-go-name": "Mode"
    },
    "port": {
      "description": "Port is the listen port.",
      "type": "integer",
      "format": "int32",
      "default": 8080,
      "x-go-name": "Port"
    },
    "verbose": {
      "description": "Verbose toggles verbose logging.",
      "type": "boolean",
      "default": false,
      "x-go-name": "Verbose"
    }
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/examples"
}

swagger:default

swagger:default is a narrow, value-only classifier hint placed on a var or const. It does not publish a spec entity of its own — it has no standalone output — so most spec defaults are carried by the default: keyword above rather than this annotation.

// DefaultPort is the fallback port used wherever Port is not supplied. The
// swagger:default annotation is a narrow value-only discovery hint.
//
// swagger:default
var DefaultPort = 8080

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

What’s next

• Other type decorators — readOnly and deprecated.
• Validations — constrain the values these examples illustrate.

Other type decorators

Beyond validations, a couple of keyword decorators annotate a property’s or operation’s role. The panes below pair the annotated Go with the fragment the scanner emits, from the test-covered docs/examples/concepts/decorators package.

For the value shapes and legal contexts of each, see the Keyword reference.

readOnly

read only: true on a model field marks the property readOnly — the server sets it, clients must not.

// Token is issued by the server.
//
// swagger:model
type Token struct {
	// ID is assigned by the server and cannot be set by clients.
	//
	// read only: true
	ID string `json:"id"`

	// Value is the token value.
	Value string `json:"value"`
}

{
  "type": "object",
  "title": "Token is issued by the server.",
  "properties": {
    "id": {
      "description": "ID is assigned by the server and cannot be set by clients.",
      "type": "string",
      "x-go-name": "ID",
      "readOnly": true
    },
    "value": {
      "description": "Value is the token value.",
      "type": "string",
      "x-go-name": "Value"
    }
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/decorators"
}

deprecated

deprecated: true in a swagger:route / swagger:operation body marks the operation deprecated.

// swagger:route GET /legacy/ping legacy ping
//
// Ping is the legacy health check.
//
// deprecated: true
//
// responses:
//
//	200: pingResponse

{
  "get": {
    "tags": [
      "legacy"
    ],
    "summary": "Ping is the legacy health check.",
    "operationId": "ping",
    "deprecated": true,
    "responses": {
      "200": {
        "$ref": "#/responses/pingResponse"
      }
    }
  }
}

What’s next

• Validations — the value-constraint keywords.
• Document metadata — the top-level spec fields.

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.

// 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
//
// swagger:meta
package meta

{
  "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"
  },
  "host": "api.example.com",
  "basePath": "/v1",
  "paths": {}
}

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

What’s next

• Routes & operations — add the paths this document describes.
• Putting it together — a complete scan from meta to definitions.

Putting it together

This capstone scans a tiny annotated “petstore” package and produces a Swagger 2.0 spec — the concepts from the pages above, assembled into one runnable example. It is the worked version of usage as a library.

The annotated API

A package-level swagger:meta block sets the top-level metadata:

// Package petstore Petstore API
//
// A tiny pet store, used to demonstrate codescan annotations: the package
// comment is a `swagger:meta` block carrying the top-level metadata of the
// generated specification (title, description, version, base path, …).
//
//	Schemes: https
//	Version: 1.0.0
//	BasePath: /v1
//
//	Consumes:
//	- application/json
//
//	Produces:
//	- application/json
//
// swagger:meta

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

A swagger:route registers a path and ties it to a response:

// swagger:route GET /pets pets listPets
//
// Lists all the pets in the store.
//
// responses:
//
//	200: petsResponse

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

A swagger:model struct becomes a definition, with field comments driving validations:

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

Running the scan

ScanPetstore builds the Options and calls codescan.Run:

opts := &codescan.Options{
	WorkDir:    workDir,                // module root to resolve patterns from
	Packages:   []string{"./petstore"}, // relative package pattern
	ScanModels: true,                   // also emit definitions for swagger:model types
}

doc, err := codescan.Run(opts)
if err != nil {
	return nil, err
}

Full source: docs/examples/basic/scan.go

The generated spec

Marshalling the returned *spec.Swagger to JSON yields the document below — the meta block became the top-level info / basePath, the swagger:route became the /pets path, and the swagger:model became the Pet definition:

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

This JSON is not hand-written: it is a golden file the example’s test regenerates and compares on every run (UPDATE_GOLDEN=1 go test ./...). Because the example is ordinary, test-covered Go, go test ./docs/examples/... keeps the page honest — if the scanner’s output changes, CI fails before the documentation can go stale.

Scoping the scan

Several options narrow what codescan looks at, independent of how individual types render. They decide which packages are loaded and which discovered operations survive into the spec.

Package patterns and WorkDir

Options.Packages takes relative go list-style patterns — ./petstore, ./... for a whole tree — resolved against Options.WorkDir (the module root). This is the worked form in the Getting started guide:

codescan.Run(&codescan.Options{
    WorkDir:    "/path/to/module",
    Packages:   []string{"./..."},
    ScanModels: true,
})

Include / Exclude

Options.Include and Options.Exclude are lists of regular expressions matched against package import paths. Include acts as an allow-list (when non-empty, only matching packages are scanned); Exclude removes matches. Use them to keep internal or generated packages out of the spec:

codescan.Run(&codescan.Options{
    Packages: []string{"./..."},
    Exclude:  []string{"/internal/", "/testdata/"},
})

Tag filters

Options.IncludeTags / Options.ExcludeTags filter operations by their Swagger tags after discovery — handy for publishing a public subset of an API while keeping the admin routes in the source:

codescan.Run(&codescan.Options{
    Packages:    []string{"./..."},
    ExcludeTags: []string{"admin", "internal"},
})

ExcludeDeps

By default codescan may follow types into dependency packages to resolve referenced models. Options.ExcludeDeps keeps the scan within your own module, leaving out types pulled in from dependencies.

Build constraints get their own guide — see Build tags.

When the scanner emits a type

codescan does not emit a definition for every type it can see. A named type reaches the spec when either of these holds:

• it is reachable — referenced (directly or transitively) from an operation, parameter, response, or another emitted model; or
• it is registered — annotated swagger:model, which (with Options.ScanModels) publishes it even when nothing references it.

A type that is neither reachable nor registered is simply absent — the scanner never invents it. The package below has one of each case:

// Order is reached only through Cart below. A referenced named type is emitted
// as a $ref target even without swagger:model.
type Order struct {
	// ID is the order identifier.
	ID string `json:"id"`
}

// Cart references Order, so Order gets a definition and the field a $ref.
//
// swagger:model
type Cart struct {
	// Order is the referenced (and therefore emitted) nested model.
	Order Order `json:"order"`
}

// Standalone is never referenced, but swagger:model together with ScanModels
// publishes it anyway.
//
// swagger:model
type Standalone struct {
	// Label is a free-text label.
	Label string `json:"label"`
}

// Orphan is never referenced and carries no swagger:model — the scanner does
// not invent it, so it never reaches the spec.
type Orphan struct {
	// Secret is internal.
	Secret string `json:"secret"`
}

Full source: docs/examples/shaping/discovery/discovery.go

Scanned with ScanModels: true, the definitions are:

{
  "Cart": {
    "type": "object",
    "title": "Cart references Order, so Order gets a definition and the field a $ref.",
    "properties": {
      "order": {
        "$ref": "#/definitions/Order"
      }
    },
    "x-go-package": "github.com/go-openapi/codescan/docs/examples/shaping/discovery"
  },
  "Order": {
    "description": "Order is reached only through Cart below. A referenced named type is emitted\nas a $ref target even without swagger:model.",
    "type": "object",
    "properties": {
      "id": {
        "description": "ID is the order identifier.",
        "type": "string",
        "x-go-name": "ID"
      }
    },
    "x-go-package": "github.com/go-openapi/codescan/docs/examples/shaping/discovery"
  },
  "Standalone": {
    "description": "Standalone is never referenced, but swagger:model together with ScanModels\npublishes it anyway.",
    "type": "object",
    "properties": {
      "label": {
        "description": "Label is a free-text label.",
        "type": "string",
        "x-go-name": "Label"
      }
    },
    "x-go-package": "github.com/go-openapi/codescan/docs/examples/shaping/discovery"
  }
}

Full source: docs/examples/shaping/discovery/testdata/definitions.json

• Cart — a swagger:model root.
• Order — has no swagger:model, yet it is emitted (as a $ref target) because Cart references it. You do not need to annotate every nested type.
• Standalone — a swagger:model that nothing references; ScanModels publishes it anyway.
• Orphan — neither referenced nor annotated, so it never appears.

Nullable pointers

Swagger 2.0 has no native nullable flag; the go-openapi toolchain uses the x-nullable vendor extension. Options.SetXNullableForPointers decides whether pointer-typed struct fields acquire it automatically. The model below has two pointer fields:

// Profile has required and optional (pointer) fields.
//
// swagger:model
type Profile struct {
	// Name is always present.
	Name string `json:"name"`

	// Nickname is optional.
	Nickname *string `json:"nickname"`

	// Age is optional.
	Age *int32 `json:"age"`
}

Full source: docs/examples/shaping/nullable/nullable.go

Scanned with the option off (default) and on, the pointer fields differ:

{
  "type": "object",
  "title": "Profile has required and optional (pointer) fields.",
  "properties": {
    "age": {
      "description": "Age is optional.",
      "type": "integer",
      "format": "int32",
      "x-go-name": "Age"
    },
    "name": {
      "description": "Name is always present.",
      "type": "string",
      "x-go-name": "Name"
    },
    "nickname": {
      "description": "Nickname is optional.",
      "type": "string",
      "x-go-name": "Nickname"
    }
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/shaping/nullable"
}

{
  "type": "object",
  "title": "Profile has required and optional (pointer) fields.",
  "properties": {
    "age": {
      "description": "Age is optional.",
      "type": "integer",
      "format": "int32",
      "x-go-name": "Age",
      "x-nullable": true
    },
    "name": {
      "description": "Name is always present.",
      "type": "string",
      "x-go-name": "Name"
    },
    "nickname": {
      "description": "Nickname is optional.",
      "type": "string",
      "x-go-name": "Nickname",
      "x-nullable": true
    }
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/shaping/nullable"
}

codescan.Run(&codescan.Options{
    Packages:                []string{"./..."},
    ScanModels:              true,
    SetXNullableForPointers: true,
})

Vendor extensions

By default codescan records where each spec object came from in Go via x-go-name (and x-go-package on definitions) — useful for round-tripping and code generation. Options.SkipExtensions removes them for a leaner spec.

// Widget is a small model.
//
// codescan records each field's Go origin as vendor extensions unless
// SkipExtensions is set.
//
// swagger:model
type Widget struct {
	// Label is the display label.
	Label string `json:"label"`

	// Size is the widget size in pixels.
	Size int32 `json:"size"`
}

Full source: docs/examples/shaping/extensions/extensions.go

{
  "description": "codescan records each field's Go origin as vendor extensions unless\nSkipExtensions is set.",
  "type": "object",
  "title": "Widget is a small model.",
  "properties": {
    "label": {
      "description": "Label is the display label.",
      "type": "string",
      "x-go-name": "Label"
    },
    "size": {
      "description": "Size is the widget size in pixels.",
      "type": "integer",
      "format": "int32",
      "x-go-name": "Size"
    }
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/shaping/extensions"
}

{
  "description": "codescan records each field's Go origin as vendor extensions unless\nSkipExtensions is set.",
  "type": "object",
  "title": "Widget is a small model.",
  "properties": {
    "label": {
      "description": "Label is the display label.",
      "type": "string"
    },
    "size": {
      "description": "Size is the widget size in pixels.",
      "type": "integer",
      "format": "int32"
    }
  }
}

codescan.Run(&codescan.Options{
    Packages:       []string{"./..."},
    ScanModels:     true,
    SkipExtensions: true,
})

SkipExtensions removes the scanner-derived x-go-* extensions. Extensions you author yourself (via the Extensions: keyword) are not affected.

Descriptions beside a $ref

When a struct field’s only decoration is a description and its Go type resolves to a named model (a $ref), JSON Schema draft 4 cannot carry a sibling description next to a $ref. Options.DescWithRef decides what happens to that description.

// Address is a referenced model.
//
// swagger:model
type Address struct {
	// Street is the street line.
	Street string `json:"street"`
}

// Person references Address through a field whose only decoration is a
// description.
//
// swagger:model
type Person struct {
	// Home is where the person lives.
	Home Address `json:"home"`
}

Full source: docs/examples/shaping/descref/descref.go

By default the description is dropped (a bare $ref); with DescWithRef it is preserved by wrapping the $ref in a single-arm allOf:

{
  "description": "Person references Address through a field whose only decoration is a\ndescription.",
  "type": "object",
  "properties": {
    "home": {
      "$ref": "#/definitions/Address"
    }
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/shaping/descref"
}

{
  "description": "Person references Address through a field whose only decoration is a\ndescription.",
  "type": "object",
  "properties": {
    "home": {
      "description": "Home is where the person lives.",
      "allOf": [
        {
          "$ref": "#/definitions/Address"
        }
      ],
      "x-go-name": "Home"
    }
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/shaping/descref"
}

codescan.Run(&codescan.Options{
    Packages:    []string{"./..."},
    ScanModels:  true,
    DescWithRef: true,
})

Alias rendering

A Go type alias (type Price = Money) is, to the Go type system, literally the same type as its target. codescan’s default is to treat it that way: at a use site the alias dissolves to its target, producing no definition of its own.

// Money is the underlying model.
//
// swagger:model
type Money struct {
	// Cents is the amount in cents.
	Cents int64 `json:"cents"`

	// Currency is the ISO currency code.
	Currency string `json:"currency"`
}

// Price is a Go alias of Money. By default an alias is a Go implementation
// detail: at use sites it dissolves to its target, producing no definition of
// its own.
type Price = Money

// Invoice references Price; the field resolves to Money.
//
// swagger:model
type Invoice struct {
	// Total is the invoice total.
	Total Price `json:"total"`
}

{
  "type": "object",
  "title": "Invoice references Price; the field resolves to Money.",
  "properties": {
    "total": {
      "$ref": "#/definitions/Money"
    }
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/shaping/aliases"
}

Invoice.total is typed Price, but the field resolves straight to #/definitions/Money — Price itself never appears.

Exposing an alias as a first-class entity

This is an advanced, rarely-needed case. To keep the alias name in the spec (its own definition that other schemas $ref), annotate the alias with swagger:model. Two top-level options then govern how that first-class alias definition is shaped:

• default (expand) — the alias definition is a structural copy of the target.
• RefAliases: true — the alias definition is a $ref chain to the target ({"$ref": "#/definitions/Money"}), preserving the alias name at use sites.
• TransparentAliases: true — aliases dissolve to their target everywhere, overriding the per-declaration annotation (use sites become $ref to the target, as in the default-dissolve example above).

For the precise per-mode contract and the canonical witnesses, see the swagger:alias reference and the fixtures/enhancements/alias-calibration-embed golden trio.

Overlaying a spec

Options.InputSpec seeds the scan with an existing *spec.Swagger: codescan merges what it discovers on top of it rather than starting from a blank document. Use it to keep hand-authored top-level metadata or a hand-written definition, or to compose a spec across several scans.

The scanned package contributes one model:

// Widget is discovered by the scan and merged onto the input spec.
//
// swagger:model
type Widget struct {
	// ID identifies the widget.
	ID string `json:"id"`
}

Full source: docs/examples/shaping/overlay/overlay.go

Given a base document with metadata and a hand-authored Health definition, the scan preserves all of it and adds the discovered Widget:

{
  "swagger": "2.0",
  "info": {
    "title": "Inventory API",
    "version": "1.0.0"
  },
  "host": "api.example.com",
  "basePath": "/v1",
  "paths": null,
  "definitions": {
    "Health": {
      "type": "object",
      "properties": {
        "ok": {
          "type": "boolean"
        }
      }
    }
  }
}

{
  "swagger": "2.0",
  "info": {
    "title": "Inventory API",
    "version": "1.0.0"
  },
  "host": "api.example.com",
  "basePath": "/v1",
  "paths": {},
  "definitions": {
    "Health": {
      "type": "object",
      "properties": {
        "ok": {
          "type": "boolean"
        }
      }
    },
    "Widget": {
      "type": "object",
      "title": "Widget is discovered by the scan and merged onto the input spec.",
      "properties": {
        "id": {
          "description": "ID identifies the widget.",
          "type": "string",
          "x-go-name": "ID"
        }
      },
      "x-go-package": "github.com/go-openapi/codescan/docs/examples/shaping/overlay"
    }
  }
}

var base spec.Swagger
_ = json.Unmarshal(baseSpecJSON, &base)

doc, _ := codescan.Run(&codescan.Options{
    Packages:   []string{"./..."},
    ScanModels: true,
    InputSpec:  &base,
})

The document’s info, host, basePath and the hand-authored Health definition survive untouched; only the discovered definitions are added.

Build tags

Go files can be guarded by //go:build constraints. By default codescan loads a package under the default build configuration, so tag-gated files are skipped. Options.BuildTags passes the tags through to the package loader, so the annotations in those files are scanned too.

The package has an always-present model plus this one, in a file that opens with the constraint //go:build experimental:

// Experimental is only scanned when the "experimental" build tag is set.
//
// swagger:model
type Experimental struct {
	// Beta flags a beta-only feature.
	Beta bool `json:"beta"`
}

Full source: docs/examples/shaping/buildtags/experimental.go

Scanned with no tags and with experimental, the gated Experimental model appears only in the second:

{
  "Stable": {
    "type": "object",
    "title": "Stable is always scanned.",
    "properties": {
      "name": {
        "description": "Name is the feature name.",
        "type": "string",
        "x-go-name": "Name"
      }
    },
    "x-go-package": "github.com/go-openapi/codescan/docs/examples/shaping/buildtags"
  }
}

{
  "Experimental": {
    "type": "object",
    "title": "Experimental is only scanned when the \"experimental\" build tag is set.",
    "properties": {
      "beta": {
        "description": "Beta flags a beta-only feature.",
        "type": "boolean",
        "x-go-name": "Beta"
      }
    },
    "x-go-package": "github.com/go-openapi/codescan/docs/examples/shaping/buildtags"
  },
  "Stable": {
    "type": "object",
    "title": "Stable is always scanned.",
    "properties": {
      "name": {
        "description": "Name is the feature name.",
        "type": "string",
        "x-go-name": "Name"
      }
    },
    "x-go-package": "github.com/go-openapi/codescan/docs/examples/shaping/buildtags"
  }
}

codescan.Run(&codescan.Options{
    Packages:   []string{"./..."},
    ScanModels: true,
    BuildTags:  "experimental",
})

BuildTags accepts the same comma-separated form as go build -tags.

Annotations

Annotations are the swagger:<name> markers the scanner recognises in Go doc comments. Each annotation classifies the surrounding declaration — telling the scanner “this is a model definition”, “this is a route handler”, “this is meta-information about the API” — and opens the door for keywords inside the same comment block.

There are twelve annotations. They divide cleanly by what they attach to:

• Spec-level: swagger:meta.
• Model declarations: swagger:model, swagger:strfmt, swagger:enum, swagger:allOf, swagger:alias.
• Operation declarations: swagger:route, swagger:operation.
• Companion declarations: swagger:parameters, swagger:response.
• Local hints: swagger:ignore, swagger:name, swagger:type, swagger:file, swagger:default.

This file is the author-first reference. Each entry covers:

• What the annotation does and what it produces in the spec.
• Where in the Go source it goes (package doc, type doc, field doc).
• The shape of any argument the annotation accepts.
• A short Go sample.
• A pointer to the keywords that are legal inside the block.
• A pointer to a real fixture in this repo for the full executable example.

For the per-keyword reference, see keywords.md. For the embedded sub-languages (Parameters: and Responses: body grammars, YAML extensions, etc.), see sub-languages.md. For the formal grammar, see grammar.md.

Table of contents

• How annotations attach
• Annotation argument shapes
• swagger:meta
• swagger:model
• swagger:strfmt
• swagger:enum
• swagger:allOf
• swagger:alias
• swagger:route
• swagger:operation
• swagger:parameters
• swagger:response
• swagger:ignore
• swagger:name
• swagger:type
• swagger:file
• swagger:default

How annotations attach

An annotation is recognised when it appears at the start of a comment line in a doc comment. Leading whitespace, the // marker, and any /* */ block-comment continuation noise are stripped — the lexer applies the same content-prefix-trim that every other godoc-aware tool does.

Annotations attach to whichever Go declaration owns the comment group:

• Package doc (// Package foo … followed by package foo) — carries swagger:meta.
• Type declaration (type T struct { … }, type T int, type T = Other) — carries swagger:model, swagger:strfmt, swagger:enum, swagger:allOf, swagger:alias, swagger:ignore, swagger:type.
• Function or variable declaration (func ServeAPI() { … }, var DoIt = func() { … }) — carries swagger:route, swagger:operation.
• Struct field doc — carries swagger:name, swagger:type, swagger:ignore, plus any of the keyword reference entries legal in schema / param / header context.

One comment group may carry MORE than one annotation when the combinations are semantically compatible — e.g. swagger:model + swagger:type together overrides the auto-detected Go type while still publishing the model. The grammar parses both and the builder honours both.

The first annotation in source order wins as the “primary” classifier — for example, a comment carrying swagger:model followed by swagger:ignore produces a model (the ignore is silently overridden because only the source-order-first annotation drives the short-circuit). Subsequent annotations are still parsed and visible via Block.AnnotationKind()-iteration, but the primary classifier determines which builder owns the decl.

Annotation argument shapes

After the swagger:<name> head, an annotation may carry positional arguments. The shapes:

• No args: swagger:meta, swagger:ignore, swagger:enum, swagger:allOf, swagger:file, swagger:default — bare annotation, the surrounding decl supplies the entity name.
• One IDENT arg: swagger:model Pet, swagger:response errorResponse, swagger:strfmt uuid, swagger:name fullName, swagger:type integer, swagger:alias TimestampAlias — the argument overrides or names the entity.
• One IDENT arg, optional: swagger:model (bare — derives the name from the Go decl) vs swagger:model Pet (overrides).
• List of IDENT args: swagger:parameters listItems createItem — declares the parameters group as legal for multiple operations.
• Header line: swagger:route GET /pets pets users listPets and swagger:operation GET /pets users listPets — a structured header carrying method, path, tags, and operation ID. See the per-annotation entries for the exact rules.

swagger:meta

What it does. Declares the package as the OpenAPI spec container. The scanner reads the package doc comment for 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.

Argument shape. No args. Bare annotation.

Sample.

// Package petstore Petstore API.
//
// The purpose of this application is to provide an application
// that is using plain Go code to define an API.
//
//     Schemes: http, https
//     Host: petstore.swagger.io
//     BasePath: /v2
//     Version: 1.0.0
//
//     Consumes:
//       - application/json
//
//     Produces:
//       - application/json
//
// swagger:meta
package petstore

Legal 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).

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

swagger:model

What it does. Declares a Go type as a published model. The scanner walks the type, emits a schema into the spec’s definitions map, and resolves cross-references between models.

Where it goes. On a type declaration (type T struct { … }, type T int, type T = Other, …).

Argument shape. Optional IDENT — the name the model takes in definitions. Default: the Go type’s name.

Sample.

// Pet is the petstore's primary entity.
//
// swagger:model
type Pet struct {
	// ID is the unique identifier.
	ID int64 `json:"id"`

	// Name is the pet's display name.
	Name string `json:"name"`

	// Tags categorise the pet.
	Tags []string `json:"tags,omitempty"`
}

With a name override:

// swagger:model PetWithExtras
type DetailedPet struct { … }

The type is published as #/definitions/PetWithExtras.

Legal keywords. All schema keywords plus the length / array / numeric validations on field doc comments.

Full example. fixtures/enhancements/named-struct-tags-ref/types.go.

swagger:strfmt

What it does. Marks a named type as a custom string format. Wherever the type appears as a field, the emitted schema is {type: string, format: <name>}. Useful for UUID, Email, URL-style types that have a Go type but should serialise as a JSON string with a known format.

Where it goes. On a type declaration whose underlying form is a string-marshalable type (typically implementing encoding.TextMarshaler or encoding.TextUnmarshaler).

Argument shape. Required IDENT — the format name (uuid, email, mac, etc.).

Sample.

// MAC is a hardware address rendered as a colon-separated hex string.
//
// swagger:strfmt mac
type MAC string

func (m MAC) MarshalText() ([]byte, error) { return []byte(m), nil }
func (m *MAC) UnmarshalText(b []byte) error { *m = MAC(b); return nil }

A field typed MAC emits as {type: string, format: mac}. The underlying MAC type does NOT appear as a top-level model definition (strfmt-tagged structs are replaced by their format at every reference).

Legal keywords. None at the type level beyond swagger:strfmt itself; the format name is the entire surface.

Full example. fixtures/enhancements/text-marshal/types.go.

swagger:enum

What it does. Marks a string-typed (or integer-typed) named type as an enum and collects the type’s const declarations. The values are applied inline on each model field that references the type: the property gets an enum array plus an x-go-enum-desc extension carrying the per-value godoc descriptions in <value> <doc-text> shape. The enum type itself is not emitted as a standalone definition — the values travel with each referencing property.

(Edge case: if swagger:enum names a type for which no matching const values are found, the enum semantics are dropped and the type falls through to ordinary type resolution — typically a plain definition referenced by $ref, with no enum array.)

Where it goes. On a named type declaration. The type’s const values are discovered via Go’s type-system traversal; they do not need to live in the same file. The values surface only when a model reaches the enum type through a field.

Argument shape. IDENT naming the type whose const values to collect (its own name).

Sample.

// Priority is the urgency level on a task.
//
// swagger:enum Priority
type Priority string

const (
	// PriorityLow is for tasks that can wait.
	PriorityLow Priority = "low"

	// PriorityMedium is the default.
	PriorityMedium Priority = "medium"

	// PriorityHigh is for tasks that must run soon.
	PriorityHigh Priority = "high"
)

// Task references Priority, which is what makes the enum reachable.
//
// swagger:model
type Task struct {
	Priority Priority `json:"priority"`
}

Produces (extract) — the values land on Task’s priority property, not on a Priority definition:

{
  "Task": {
    "type": "object",
    "properties": {
      "priority": {
        "type": "string",
        "enum": ["low", "medium", "high"],
        "x-go-enum-desc": "low PriorityLow is for tasks that can wait.\nmedium PriorityMedium is the default.\nhigh PriorityHigh is for tasks that must run soon."
      }
    }
  }
}

Legal keywords. Schema-context keywords. The enum: keyword can ALSO be used inline on the type doc to force a value set; when present, it overrides the const-derived values and the x-go-enum-desc is recomputed (or dropped) accordingly.

Full example. fixtures/enhancements/enum-overrides/types.go.

swagger:allOf

What it does. Marks a struct as participating in an allOf composition. The struct’s fields plus any embedded swagger:model-tagged base produce an allOf: [$ref base, {inline fields}] schema. The companion convention is to embed the base type as an anonymous field with this annotation on the embedding’s doc comment (or on the embedded type itself).

Where it goes. On a struct field that embeds another type, or on a struct type that has at least one embedded base.

Argument shape. No args.

Sample.

// Animal is the abstract base.
//
// swagger:model
type Animal struct {
	Kind string `json:"kind"`
}

// Dog is an Animal with a breed.
//
// swagger:model
type Dog struct {
	// swagger:allOf
	Animal

	Breed string `json:"breed"`
}

Produces:

"Dog": {
  "allOf": [
    {"$ref": "#/definitions/Animal"},
    {
      "type": "object",
      "properties": {
        "breed": {"type": "string", "x-go-name": "Breed"}
      }
    }
  ]
}

Legal keywords. Schema-context keywords on the inline-object member (the second allOf element).

Full example. fixtures/enhancements/allof-edges/types.go.

swagger:alias

What it does. Marks a Go alias declaration (type T = Other) as a model that should publish as a $ref to Other’s definition rather than as a duplicate of Other’s schema.

The scanner also honours RefAliases and TransparentAliases top-level options, which can globally enable alias-as-ref behaviour without per-decl annotation. swagger:alias is the per-decl override for cases where the global mode isn’t appropriate.

Where it goes. On a type alias declaration.

Argument shape. Optional IDENT — the published name. Default: the alias’s Go name.

Sample.

// Timestamp aliases time.Time. The published model carries
// format: date-time via the time.Time → strfmt resolution.
//
// swagger:alias
type Timestamp = time.Time

Without the annotation (and without global RefAliases), the alias either expands the target’s full schema or is silently ignored depending on context.

Legal keywords. Schema-context keywords.

Full example. fixtures/enhancements/ref-alias-chain/types.go.

swagger:route

What it does. Declares an HTTP route + operation in one annotation. The header line carries the method, path, optional tags, and the operation ID; the comment body carries the operation’s metadata (consumes / produces / schemes / security / parameters / responses / extensions).

This is the terser of the two operation-declaration annotations. Most go-swagger projects use swagger:route for hand-written operations.

Where it goes. On a function or variable declaration whose doc comment carries the annotation. The Go entity itself doesn’t have to be a handler — the annotation publishes a path/operation independent of the carrier.

Argument shape. Header line:

swagger:route <METHOD> <path> [tag1 tag2 …] <operationID>

• <METHOD> — GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS. Case insensitive.
• <path> — starts with /. Supports path-parameter braces: /items/{id}.
• [tag1 tag2 …] — optional whitespace-separated list of tags. At least two characters each.
• <operationID> — the unique operation identifier.

A godoc-style identifier may precede the annotation on the same comment line:

// ListPets swagger:route GET /pets pets users listPets

That leading identifier is recognised as a godoc convention and is not part of the annotation surface.

Sample.

// ListPets swagger:route GET /pets pets users listPets
//
// List pets filtered by some parameters.
//
//     Consumes:
//       - application/json
//
//     Produces:
//       - application/json
//
//     Schemes: http, https
//
//     Security:
//       api_key:
//       oauth: read, write
//
//     Parameters:
//       + name: limit
//         in: query
//         type: integer
//         minimum: 1
//         maximum: 100
//
//     Responses:
//       200: body:[]Pet the pet list
//       default: response:genericError
func ListPets() {}

Legal keywords. All body keywords legal in route context (consumes, produces, schemes, security, parameters, responses, extensions) plus inline deprecated:.

The Parameters: and Responses: sub-languages are documented in sub-languages.md §parameters and sub-languages.md §responses.

Full example. fixtures/enhancements/routes-full-petstore-shape/handlers.go.

swagger:operation

What it does. Same payload as swagger:route but with a different body shape: instead of the structured Parameters: / Responses: keyword surface, swagger:operation’s body is a single YAML document spelling out the OpenAPI operation object directly.

Use swagger:operation when you want to author the operation in YAML (closer to the OpenAPI spec text) or when the operation has shapes the keyword surface doesn’t cover.

Where it goes. Same as swagger:route — function or variable doc comment.

Argument shape. Same header shape as swagger:route:

swagger:operation <METHOD> <path> [tag1 tag2 …] <operationID>

Sample.

// swagger:operation GET /items/{id} items getItem
//
// ---
// summary: Get item by ID
// parameters:
//   - name: id
//     in: path
//     required: true
//     type: integer
// responses:
//   '200':
//     description: the requested item
//     schema:
//       $ref: '#/definitions/Item'
//   default:
//     $ref: '#/responses/genericError'
func GetItem() {}

The --- delimits the YAML body; everything between the fences is parsed as an OpenAPI 2.0 operation object.

Legal keywords. None inside the YAML body (it’s structurally YAML, not the keyword grammar). The header line is the entire annotation surface.

Full example. fixtures/enhancements/parameters-map-postdecl/api.go.

swagger:parameters

What it does. Declares a Go struct as the parameters set for one or more operations. Each field of the struct becomes one parameter on the named operation(s). The field’s doc comment carries the parameter’s in:, required:, validation, and description.

Where it goes. On a struct declaration.

Argument shape. Required IDENTs — the operation IDs this parameters set applies to. At least one. The same operation ID may appear in multiple swagger:parameters annotations to compose a parameter set from several structs.

Sample.

// ListItemsParams declares pagination + filter parameters for the
// listItems operation.
//
// swagger:parameters listItems
type ListItemsParams struct {
	// Offset is the page offset.
	//
	// in: query
	// minimum: 0
	// default: 0
	Offset int `json:"offset"`

	// Limit is the page size.
	//
	// in: query
	// minimum: 1
	// maximum: 100
	// default: 20
	Limit int `json:"limit"`

	// Tag is the filter tag.
	//
	// in: query
	// required: false
	Tag string `json:"tag,omitempty"`
}

Legal keywords on fields. param-context keywords (in, required, the numeric / length / format validations, default, example, enum, allowEmptyValue, collectionFormat).

Full example. fixtures/enhancements/simple-schema-violation/api.go.

swagger:response

What it does. Declares a Go struct as a named response object, emitted into the spec’s top-level responses map. Routes / operations reference it by name via the response sub-language (Responses: body in swagger:route, or the YAML $ref form in swagger:operation).

The struct’s fields contribute the response shape:

• A field named Body (or carrying in: body) becomes the response body schema.
• Other fields carrying in: header become response headers.

Where it goes. On a struct declaration.

Argument shape. Optional IDENT — the published response name. Default: the Go type’s name.

Sample.

// GenericError is the catch-all error response.
//
// swagger:response genericError
type GenericError struct {
	// in: body
	Body struct {
		// Message is the human-readable error message.
		Message string `json:"message"`

		// Code is the machine-readable error category.
		Code string `json:"code,omitempty"`
	}

	// X-Request-ID echoes the request correlation header.
	//
	// in: header
	XRequestID string `json:"X-Request-ID"`
}