📖 2 min read (~ 400 words).

Petstore

The Swagger Petstore is the canonical OpenAPI 2.0 sample. The generated/ example is that spec run through swagger generate server — a complete server scaffold for a multi-resource API, useful as a reference for what a “full” spec produces.

Tip

Source: generated/. Generated with swagger generate server --name Petstore --spec ./swagger-petstore.json --principal any.

Three resource groups

The petstore spec organizes operations under three tags, each becoming its own package of generated handlers:

  • pet — addPet, updatePet, findPetsByStatus, findPetsByTags, getPetById, deletePet, uploadFile
  • store — getInventory, placeOrder, getOrderById, deleteOrder
  • user — createUser, getUserByName, loginUser, logoutUser, …

A generated model

The Pet model shows the usual spec-to-Go mapping — required fields as pointers, nested models by reference, arrays as slices — alongside a generated Validate method (not shown) that enforces the spec’s constraints:

type Pet struct {

	// category
	Category *Category `json:"category,omitempty"`

	// id
	ID int64 `json:"id,omitempty"`

	// name
	// Example: doggie
	// Required: true
	Name *string `json:"name"`

	// photo urls
	// Required: true
	PhotoUrls []string `json:"photoUrls"`

	// pet status in the store
	Status string `json:"status,omitempty"`

	// tags
	Tags []*Tag `json:"tags"`
}

Full source: generated/models/pet.go

Two security schemes

Petstore mixes an api-key header with an OAuth2 flow. The generator emits a distinct authenticator hook for each — note the OAuth2 hook receives the required scopes so you can authorize per operation:

// Applies when the "api_key" header is set
if api.APIKeyAuth == nil {
	api.APIKeyAuth = func(token string) (any, error) {
		_ = token

		return nil, errors.NotImplemented("api key auth (api_key) api_key from header param [api_key] has not yet been implemented")
	}
}
if api.PetstoreAuthAuth == nil {
	api.PetstoreAuthAuth = func(token string, scopes []string) (any, error) {
		_ = token
		_ = scopes

		return nil, errors.NotImplemented("oauth2 bearer auth (petstore_auth) has not yet been implemented")
	}
}

Full source: generated/restapi/configure_petstore.go

See the OAuth2 guide for a fully implemented flow.

Typed vs untyped

This repo also ships the same petstore API hand-wired without codegen, using the go-openapi runtime directly, under 2.0/petstore. That untyped style — building the API from runtime primitives rather than generated code — is the subject of the go-openapi/runtime site. Compare the two to see exactly what swagger generate buys you.