sashay

Overview ¶

Package sashay allows you to generate OpenAPI 3.0 (Swagger) files using executable Go code, including the same types you already use for parameter declaration and serialization.

You don't have to worry about creating extensive Swagger-specific comments or editing a Swagger file by hand. You can get a good enough Swagger document with very little work, using the code you already have!

- Use your existing serializable Go structs to document what an endpoint returns. Really, Sashay will figure out the OpenAPI contents using reflection.

- Declare your parameters using Go structs. If you are binding and validating using structs in your endpoint handlers, you can use the same structs for Sashay.

- You can extend Sashay to handle your own types and struct tags, such as if you use custom time/date types, or want to parse validation struct tags into something you can place in your OpenAPI doc.

Creating a nicer OpenAPI 3.0 document from your existing code is generally a matter of adding a bit of annotation to struct tags or using some Sashay types around your API's types.

See https://swagger.io/specification/ for more information about the OpenAPI 3.0 spec.

Sashay Tutorial ¶

There are generally three parts to defining and generating Swagger docs using Sashay:

- Define the sashay.Sashay registry which holds all information that will be in the document. This is usually a singleton for an entire service, or passed to all route registration.

- Define new sashay.Operation instances where you have your handlers, adding them to the registry using the Add method as you go.

- Generate the YAML string using the WriteYAML method.

In the following sections, we will go through the steps to build something very similar to the "Pet Store API" Swagger example. This is the default example API at https:/editor.swagger.io/#/.

The "Pet Store API" OpenAPI 3.0 YAML file the service is based on is here: https://github.com/OAI/OpenAPI-Specification/blob/master/examples/v3.0/petstore-expanded.yaml

There is code for a "Pet Store API" Go server here: https://github.com/swagger-api/swagger-codegen/blob/master/samples/server/petstore/go-api-server/go/routers.go Note that this is for their Swagger 2.0 definition, which is much larger than the 3.0 definition.

Our code will be based off that Pet Store code. There are many ways to structure a Go service; the Pet Store example is only one such structure, with centralized routing and general HTTP handlers. Sashay, being a library, can fit into any application setup. It just needs to get the right calls, which should be clear by the end, as the API has very few moving parts.

Tutorial Step 1- Define Service Level Settings ¶

In our example petstore.yaml file, we have the following settings that apply to the service, rather than any specific paths, operations, or resources:

openapi: 3.0.0
info:
  title: Swagger Petstore
  description: A sample API that uses a petstore as an example to demonstrate features in the OpenAPI 3.0 specification
  termsOfService: http://swagger.io/terms/
  contact:
    email: apiteam@swagger.io
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.0
tags:
  - name: pet
    description: Everything about your Pets
  - name: store
    description: Access to Petstore orders
  - name: user
    description: Operations about user
servers:
  - url: http://petstore.swagger.io/api
    description: Public API server
security:
  - apiKeyAuth: []

We can use the following code to create a *sashay.Sashay object that will generate that YAML. This can be a stateful singleton, placed somewhere accessible to all handlers and routers, like some common or config file. Later in our example, we create the instance in our main function, and pass it to the router:

sa := sashay.New(
	"Swagger Petstore",
	"A sample API that uses a petstore as an example to demonstrate features in the OpenAPI 3.0 specification",
	"1.0.0").
	AddAPIKeySecurity("header", "api_key").
	SetTermsOfService("http://swagger.io/terms/").
	SetContact("", "", "apiteam@swagger.io").
	SetLicense("Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0.html").
	AddServer("http://petstore.swagger.io/api", "Public API server").
	AddTag("pet", "Everything about your Pets").
	AddTag("store", "Access to Petstore orders").
	AddTag("user", "Operations about user")

The way this code maps to the YAML should be pretty self-explanatory. For more information on any of these, you can refer to the OpenAPI documentation, as it maps cleanly.

This code uses "apiKey" security, via AddAPIKeySecurity. The sashay.Sashay object also has AddBasicAuthSecurity and AddJWTSecurity methods available.

Tutorial Step 2- Define Operations ¶

An "operation" in OpenAPI 3.0 is a description for a path/route and method. For example, here is the GET /pets endpoint Swagger YAML:

paths:
  /pets:
    get:
      operationId: getPets
      summary: Returns all pets from the system that the user has access to
      parameters:
        - name: tags
          in: query
          description: tags to filter by
          schema:
            type: array
            items:
              type: string
        - name: limit
          in: query
          description: maximum number of results to return
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: ok response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'
        'default':
          description: error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

Let's go through the Go code required for that YAML.

First there is the code for the models. These are probably not endpoint-specific, but shared for the entire application. There is nothing swagger-related to this code; it already exists for the service:

type Pet struct {
	ID   int    `json:"id"`
	Name string `json:"name"`
	Tag  string `json:"tag"`
}
type Error struct {
	Code    int32  `json:"code"`
	Message string `json:"message"`
}

Next there is the actual route handler. This also has nothing Swagger-specific. It is code that already exists for your service.

func GetPets (http.ResponseWriter, *http.Request) {
	// Your code here
}

Finally, we get to the route definitions/registration. This, too, is something that needs to happen for any service. The changes here have to do with registering a route adding it both to your HTTP framework's router, and the sashay.Sashay registry. Note that the sashay.Operation object has the method and path necessary to register routes in pretty much every framework. In this code, we have a custom Route struct that marries the Operation along with an http.HandlerFunc.

type Route struct {
	operation sashay.Operation
	handler   http.HandlerFunc
}

func RegisterRoutes(router *FrameworkRouter, sw *sashay.Sashay) {
	for _, route := range routes {
		sw.Add(route.operation)
		router.AddRoute(route.operation.Method, route.operation.Path, route.handler)
	}
}

var routes = []Route{
	{
		sashay.NewOperation(
			"GET",
			"/pets",
			"Returns all pets from the system that the user has access to",
			struct {
				Tags  []string `query:"tags" description:"tags to filter by"`
				Limit int32    `query:"limit" description:"maximum number of results to return"`
			}{},
			[]Pet{},
			Error{},
		),
		GetPets,
	},
}

Tutorial Step 3- Generate the OpenAPI File ¶

Finally, there is the server startup code, usually in some sort of main() function. This code initializes a new sashay.Sashay instance, registers routes, and writes to a yaml file if the program is run with a -swagger argument. This code in particular is going to be different depending on your conventions; the following code is just an idea to show how this all fits together.

func StartServer() {
	sw := PetStoreSwagger()
	router := &FrameworkRouter{}
	RegisterRoutes(router, sw)
	if len(os.Args) > 0 && os.Args[0] == "-swagger" {
		yaml := sw.BuildYAML()
		ioutil.WriteFile("swagger.yml", []byte(yaml), 0644)
		os.Exit(0)
	}
	http.ListenAndServe(":8080", router)
}

func PetStoreSwagger() *sashay.Sashay {
	return swagger.New(
		"Swagger Petstore",
		"A sample API that uses a petstore as an example to demonstrate features in the OpenAPI 3.0 specification",
		"1.0.0").
		AddAPIKeySecurity("header", "api_key").
		SetTermsOfService("http://swagger.io/terms/").
		SetContact("", "", "apiteam@swagger.io").
		SetLicense("Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0.html").
		AddServer("http://petstore.swagger.io/api", "Public API server").
		AddTag("pet", "Everything about your Pets").
		AddTag("store", "Access to Petstore orders").
		AddTag("user", "Operations about user")
}

That's all there is to it. You can see a fuller example in the petstore_test.go file, which contains the preceding code but with more routes.

Sashay Detail- Basic Parameters ¶

The sashay.Operation object supports defining an endpoint's parameters. Because parameter settings can be quite detailed, this package will parse some parameter settings from struct tags. Let's look at the Parameters field in the following sashay.Operation definition:

sashay.NewOperation(
	"POST",
	"/users/:id",
	"Update the user.",
	struct {
		ID int `path:"id" validate:"min=1"`
		Pretty bool `query:"pretty" description:"If true, return pretty-printed JSON." default:"true"`
		NoResponse bool `header:"X-NO-RESPONSE" description:"If true, return a 204 rather than the updated User."`
		Name string `json:"name"`
	}{},
	nil,
	nil,
)

The struct tags of "path", "header", and "query" define the name of the parameter in the path/header/query. Using the "json" tag indicates the parameter is included in the request body. This Operation generates the following YAML:

paths:
  /users/{id}:
	post:
	  operationId: postUsersId
	  summary: Update the user.
	  parameters:
		- name: id
		  in: path
		  required: true
		  schema:
			type: integer
			format: int64
		- name: pretty
		  in: query
		  description: If true, return pretty-printed JSON.
		  schema:
			type: boolean
			default: true
		- name: X-NO-RESPONSE
		  in: header
		  description: If true, return a 204 rather than the updated User.
		  schema:
			type: boolean
	  requestBody:
		required: true
		content:
		  application/json:
			schema:
			  type: object
			  properties:
				name:
				  type: string
	  responses:
		'204':
		  description: The operation completed successfully.
		'default':
		  description: error response

The parameter struct definitions are nice, but the best feature is that they are actually executable Go code that you can use for the parameter validation and binding in your own endpoints! In practice, your Operation definitions will look something like this:

type getUsersParams struct {
	Status string `query:"status" validate:"eq=active|eq=deleted"`
}
getUsersOp := sashay.NewOperation(
	"GET",
	"/users",
	"Get users",
	getUsersParams{},
	[]User{},
	ErrorModel{},
)
getUsersHandler := func(c echo.Context) error {
	params := getUsersParams{}
	if err := c.Bind(&params); err != nil {
		return err
	}
	if err := c.Validate(params); err != nil {
		return err
	}
	var users []User
	// Logic to get users
	return c.JSON(200, users)
}

sw.Add(getUsersOp)
router.Add(getUsersOp.Method, getUsersOp.Path, getUsersHandler)

The actual getUsersHandler code uses the same struct to describe itself as it does in code. The same is true for response types- the schema is built from the real objects, with the json struct tags, not separate documentation.

Note that Sashay never uses $ref for parameters (resources in POST/PUT request bodies). Even if the same type is used for a request and a response, it'll be expanded in the requestBody section and a $ref in the response section. This may change in the future.

Sashay Detail- Request Bodies ¶

Struct types can also be used in parameters. Usually, these will be nested structs for request bodies:

sashay.NewOperation(
	"POST",
	"/users",
	"Create a user.",
	struct {
		Name struct {
			First string `json:"first"`
			Last string `json:"last"`
		} `json:"name"`
	}{},
	nil,
	nil,
)

You can see the requestBody YAML it generates:

paths:
  /users:
	post:
	  operationId: postUsers
	  summary: Create a user.
	  requestBody:
		required: true
		content:
		  application/json:
			schema:
			  type: object
			  properties:
				name:
				  type: object
				  properties:
					first:
					  type: string
					last:
					  type: string

Sashay Detail- Representing Custom Types ¶

Note that out of the box, Sashay will treat simple custom types (like `type MyString string`) as their underlying simple type, and will walk any custom structs.

However, sometimes you want to use Go struct types that are represented as data types in Swagger. Times are an exampmle of this: time.Time is a Go struct type, but we want to represent it with a string data type in Swagger (type: string, format: date-time). For example, let's say "month" is a common concept in our API, so we represent it with a type:

type Month struct {
	Year int
	Month int
}

type Params struct {
	Month Month `query:"month"`
}

When we have a struct field with a type of MyTime, we would normally get a schema of:

type: object
properties:
  time:
    type: object
    properties:
      year:
        type: integer
      month:
        type: integer

However, what we actually want is something like this:

type: object
properties:
  time:
    type: string
    format: YYYY-MM

We can define a mapping between custom types and a "data type transformer" to do this. For example, to get the desired Swagger we would use a SimpleDataTyper transformer:

sa.DefineDataType(Month{}, SimpleDataTyper("string", "YYYY-MM"))

DefineDataType takes in an instance of a value to map into a data type and the DataTyper transformer function. SimpleDataTyper uses the given type and format strings.

Sashay includes other built-in DataTypers:

- DefaultDataTyper() will parse the "default" struct tag and write it into the "default" field.

- ChainDataTyper calls one DataTyper after another. The most common usage is to use this around SimpleDataTyper and DefaultDataTyper, but feel free to get creative.

- BuiltinDataTyperFor returns the default DataTyper behavior for a type. This is useful when you want to extend the behavior for a built-in type, but not entirely replace it (we use it below, for a custom string data typer behavior).

The DataTyper function can get more creative, too. For example, it can parse struct fields to inform what should write into the Swagger file. Consider a "unit of time" type that can be used for any unit, rather than custom month, day, etc types:

type UnitOfTime struct {
	time time.Time
	unit string
}

And using it for parameters looks like:

type Params struct {
	Month UnitOfTime `query:"month" timeunit:"month"`
}

We could use a DataTyper that reads the "timeunit" struct tag, and specifies the "format" field based on that:

sw.DefineDataType(UnitOfTime{}, func(f sashay.Field, of sashay.ObjectFields) {
	of["type"] = "string"
	if timeunit := f.StructField.Tag.Get("timeunit"); timeunit != "" {
		switch timeunit {
		case "date":
			of["format"] = "date"
		case "month":
			of["format"] = "YYYY-MM"
		}
	}
})

Sashay Detail- Other Advanced DataTyper Usage ¶

We can use DefineDataType to customize all sorts of behavior. One common usage is parsing tags to specify other information about a field, like we did with "timeunit" above. Perhaps we want to parse an "enum" tag that specifies valid values for a string field:

extractEnum := func(f sashay.Field, of sashay.ObjectFields) {
	of["type"] = "string"
	if enum := f.StructField.Tag.Get("enum"); enum != "" {
		values := strings.Split(enum, "|")
		of["enum"] = fmt.Sprintf("['%s']", strings.Join(values, "', '"))
	}
}
sw.DefineDataType("", sashay.BuiltinDataTyperFor("", extractEnum))

Now, when we have a string with the "enum" struct tag, we will get the "enum" field in our YAML:

type Params struct {
	Status string `json:"status" enum:"on|off"`
}

schema:
  type: object
  properties:
    status:
      type: string
      enum: ['on', 'off']

The goal of Sashay is, you may recall, to reuse as much of your existing code as possible, and to build off it rather than require a bunch of custom annotation or documentation. In practice, this often means pulling this sort of data out of "validation" struct tags, rather than custom struct tags like "enum" or "timeunit", but the idea is the same.

For an example of this in action, and a good basis for hooking your own validation needs up to Sashay, see validator_data_typer_test.go. It includes a fully-functional example using go-validator style struct tags to inform data type fields.

Sashay Detail- Responses ¶

The other part of sashay.Operation that may require some customization are usually responses. Sashay tries to be smart and enforce some conventions:

- Successful POSTs returns a 201. - All other successful methods return a 200. - All operations get a 'default' error response.

For example, let's look at the Go code to fetch an array of users (we can use an empty User slice, or a custom Users slice type would work fine).

sashay.NewOperation(
	"GET",
	"/users",
	"",
	nil,
	[]User{},
	ErrorModel{},
)

The 200 response is an array that points to references of the User schema, and the User and Error Model are defined in components/schemas:

paths:
  /users:
	get:
	  operationId: getUsers
	  responses:
		'200':
		  description: ok response
		  content:
			application/json:
			  schema:
				type: array
				items:
				  $ref: '#/components/schemas/User'
		'default':
		  description: error response
		  content:
			application/json:
			  schema:
				$ref: '#/components/schemas/ErrorModel'
components:
  schemas:
	ErrorModel:
	  type: object
	  properties:
		error:
		  type: object
		  properties:
			message:
			  type: string
			code:
			  type: integer
			  format: int64
	User:
	  type: object
	  properties:
		result:
		  type: object
		  properties:
			id:
			  type: integer
			  format: int64
			name:
			  type: string

However, sometimes you need more advanced response information. In particular, you may want to document specific error conditions or return type shapes. You can use the swagger.Response or swagger.Responses object for this:

sashay.NewOperation(
	"GET",
	"/is_teapot",
	"Error if the server is a teapot.",
	nil,
	swagger.Responses{
		swagger.NewResponse(200, "Not a teapot.", TeapotResponse{}),
		swagger.NewResponse(203, "I may not be a teapot", TeapotResponse{}),
	},
	swagger.NewResponse(418, "Yes, I am sure a teapot!", TeapotError{}),
)

Note the calls to NewResponse, and the Responses slice. In this way, the default codes can be overwritten, and multiple responses can be specified:

paths:
  /is_teapot:
	get:
	  operationId: getIsTeapot
	  summary: Error if the server is a teapot.
	  responses:
		'200':
		  description: Not a teapot.
		  content:
			application/json:
			  schema:
				$ref: '#/components/schemas/TeapotResponse'
		'203':
		  description: I may not be a teapot
		  content:
			application/json:
			  schema:
				$ref: '#/components/schemas/TeapotResponse'
		'418':
		  description: Yes, I am sure a teapot!
		  content:
			application/json:
			  schema:
				$ref: '#/components/schemas/TeapotError'

Finally, there are a couple special cases for responses:

- If a response is a string type, rather than a struct, it is assumed to be of content type text/plain.

- If a response is an empty struct (`struct{}{}`), use application/json with no schema.

Sashay Detail- Pointer Fields ¶

Sashay treats value and pointer fields the same. In other words, *bool and bool will use the same data type/schema. When you register a data type (refer to DefineDataType), the same DataTyper is used for pointer fields of that type.

The primary use case for pointer fields in Go is to represent optional fields. There's nothing much for Sashay to do with that information, because both parameters and object fields are optional/not-required in Swagger by default. For example, in parameters, "required: false" is the default. And for schemas (request bodies, responses), the "nullable: true" attribute is quite semantically different than the "optional" meant by a Go pointer field.

In the future, Sashay may support more more extensive specification around required fields, but not right now.

package main

import (
	"fmt"
	"github.com/rgalanakis/sashay"
	"io/ioutil"
	"net/http"
	"os"
)

// Stand-in for whatever HTTP framework you are using
type FrameworkRouter struct{}

func (FrameworkRouter) ServeHTTP(http.ResponseWriter, *http.Request)     {}
func (FrameworkRouter) AddRoute(method, path string, h http.HandlerFunc) {}

// main.go
func PetStoreSwagger() *sashay.Sashay {
	return sashay.New(
		"Swagger Petstore",
		"A sample API that uses a petstore as an example to demonstrate features in the OpenAPI 3.0 specification",
		"1.0.0").
		AddAPIKeySecurity("header", "api_key").
		SetTermsOfService("http://swagger.io/terms/").
		SetContact("", "", "apiteam@swagger.io").
		SetLicense("Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0.html").
		AddServer("http://petstore.swagger.io/api", "Public API server").
		AddTag("pet", "Everything about your Pets").
		AddTag("store", "Access to Petstore orders").
		AddTag("user", "Operations about user")
}

// noinspection GoUnusedExportedFunction
func StartServer() {
	sw := PetStoreSwagger()
	router := &FrameworkRouter{}
	RegisterRoutes(router, sw)
	if len(os.Args) > 0 && os.Args[0] == "-swagger" {
		yaml := sw.BuildYAML()
		ioutil.WriteFile("swagger.yml", []byte(yaml), 0644)
		os.Exit(0)
	}
	http.ListenAndServe(":8080", router)
}

// handlers.go file
// noinspection GoUnusedParameter
func GetPets(http.ResponseWriter, *http.Request) {
	// Your code here
}

var CreatePet http.HandlerFunc
var GetPet http.HandlerFunc
var DeletePet http.HandlerFunc

// models.go file
type Pet struct {
	ID   int    `json:"id"`
	Name string `json:"name"`
	Tag  string `json:"tag"`
}
type Error struct {
	Code    int32  `json:"code"`
	Message string `json:"message"`
}

// routes.go file
type Route struct {
	operation sashay.Operation
	handler   http.HandlerFunc
}

func RegisterRoutes(router *FrameworkRouter, sw *sashay.Sashay) {
	for _, route := range routes {
		sw.Add(route.operation)
		router.AddRoute(route.operation.Method, route.operation.Path, route.handler)
	}
}

var routes = []Route{
	{
		sashay.NewOperation(
			"GET",
			"/pets",
			"Returns all pets from the system that the user has access to",
			struct {
				Tags  []string `query:"tags" description:"tags to filter by"`
				Limit int32    `query:"limit" description:"maximum number of results to return"`
			}{},
			[]Pet{},
			Error{},
		), GetPets,
	}, {
		sashay.NewOperation(
			"POST",
			"/pets",
			"Creates a new pet in the store.  Duplicates are allowed",
			struct {
				Name string `json:"name"`
				Tag  string `json:"tag"`
			}{},
			sashay.NewResponse(200, "pet response", Pet{}), // Normally a 201
			Error{},
		), CreatePet,
	}, {
		sashay.NewOperation(
			"GET",
			"/pets/:id",
			"Returns a user based on a single ID, if the user does not have access to the pet",
			struct {
				ID int `path:"id" description:"ID of pet to fetch"`
			}{},
			Pet{},
			Error{},
		), GetPet,
	}, {
		sashay.NewOperation(
			"DELETE",
			"/pets/:id",
			"deletes a single pet based on the ID supplied",
			struct {
				ID int `path:"id" description:"ID of pet to delete"`
			}{},
			nil, // 204 response
			Error{},
		), DeletePet,
	},
}

func main() {
	sw := PetStoreSwagger()
	RegisterRoutes(&FrameworkRouter{}, sw)
	fmt.Println(sw.BuildYAML())
}

Output:
openapi: 3.0.0
info:
  title: Swagger Petstore
  description: A sample API that uses a petstore as an example to demonstrate features in the OpenAPI 3.0 specification
  termsOfService: http://swagger.io/terms/
  contact:
    email: apiteam@swagger.io
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.0
tags:
  - name: pet
    description: Everything about your Pets
  - name: store
    description: Access to Petstore orders
  - name: user
    description: Operations about user
servers:
  - url: http://petstore.swagger.io/api
    description: Public API server
paths:
  /pets:
    get:
      operationId: getPets
      summary: Returns all pets from the system that the user has access to
      parameters:
        - name: tags
          in: query
          description: tags to filter by
          schema:
            type: array
            items:
              type: string
        - name: limit
          in: query
          description: maximum number of results to return
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: ok response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'
        'default':
          description: error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: postPets
      summary: Creates a new pet in the store.  Duplicates are allowed
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                tag:
                  type: string
      responses:
        '200':
          description: pet response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
        'default':
          description: error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /pets/{id}:
    get:
      operationId: getPetsId
      summary: Returns a user based on a single ID, if the user does not have access to the pet
      parameters:
        - name: id
          in: path
          required: true
          description: ID of pet to fetch
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: ok response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
        'default':
          description: error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: deletePetsId
      summary: deletes a single pet based on the ID supplied
      parameters:
        - name: id
          in: path
          required: true
          description: ID of pet to delete
          schema:
            type: integer
            format: int64
      responses:
        '204':
          description: The operation completed successfully.
        'default':
          description: error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      type: object
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
    Pet:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        tag:
          type: string
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: api_key
security:
  - apiKeyAuth: []

package main

import (
	"fmt"
	"github.com/rgalanakis/sashay"
)

func main() {
	type Pet struct {
		ID   int    `json:"id"`
		Name string `json:"name"`
		Tag  string `json:"tag"`
	}
	type Error struct {
		Code    int32  `json:"code"`
		Message string `json:"message"`
	}

	sw := sashay.New("PetStore API", "Manage your pet store with our API", "1.0.0")
	sw.Add(sashay.NewOperation(
		"GET",
		"/pets",
		"Return all pets.",
		struct {
			Status string `query:"status"`
		}{},
		[]Pet{},
		Error{},
	))
	sw.Add(sashay.NewOperation(
		"POST",
		"/pets",
		"Create a pet.",
		struct {
			Pretty bool   `query:"pretty" default:"true" description:"If true, return pretty-printed JSON."`
			Name   string `json:"name"`
		}{},
		Pet{},
		Error{},
	))
	sw.Add(sashay.NewOperation(
		"GET",
		"/pets/:id",
		"Fetch info about a pet.",
		struct {
			ID   int    `path:"id"`
			Name string `json:"name"`
		}{},
		Pet{},
		Error{},
	))
	fmt.Println(sw.BuildYAML())
}

Output:
openapi: 3.0.0
info:
  title: PetStore API
  description: Manage your pet store with our API
  version: 1.0.0
paths:
  /pets:
    get:
      operationId: getPets
      summary: Return all pets.
      parameters:
        - name: status
          in: query
          schema:
            type: string
      responses:
        '200':
          description: ok response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'
        'default':
          description: error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: postPets
      summary: Create a pet.
      parameters:
        - name: pretty
          in: query
          description: If true, return pretty-printed JSON.
          schema:
            type: boolean
            default: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
      responses:
        '201':
          description: ok response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
        'default':
          description: error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /pets/{id}:
    get:
      operationId: getPetsId
      summary: Fetch info about a pet.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: ok response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
        'default':
          description: error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      type: object
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
    Pet:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        tag:
          type: string