oas

README

OAS Schemagen

The initial purpose of this setup is so that eventually any of our repos would be able to import the package and use the methods to compose a wholly unique OpenAPI specification, append to an existing "base" specification, or merge between specifications.

This setup is not yet complete. There are weird quirks between all of the libraries and today ogen is controlling the largest swath of our generated specs, this is the first attempt at composing + outputting specifications based on the REST handlers and interfaces.

Eventually we may be able to use ast, packages, and other walking methods to reference / fetch the structs but for now the handler methods are added through basic functions which map them in the specification correctly.

TO DO

• Add examples to all Components and associated

Documentation

Index

• Variables
• func AddErrorSchemas(gen *OAS)
• func AddExamples(gen *OAS)
• func AddHandlers(gen *OAS)
• func AddParameters(gen *OAS)
• type OAS
  • func NewSchemaGenerator() *OAS
  • func (s *OAS) AddExample(name string, value interface{})
  • func (s *OAS) AddHeader(name string, header *openapi3.Header)
  • func (s *OAS) AddQueryParameter(name string, value Parameter)
  • func (s *OAS) AddRequestBody(name string, body interface{})
  • func (s *OAS) AddResponse(name string, description string, ref string, example interface{})
  • func (s *OAS) AddSchema(name string, model interface{})
  • func (s *OAS) AddSecurityScheme(name string, scheme *openapi3.SecurityScheme)
• type Parameter

Variables

var TokenQuery = Parameter{
	Name:        "token",
	Description: "the token to parse out of a URL",
	Type:        "integer",
	Required:    true,
	In:          "query",
}

TokenQuery is a parameter for the token query

Functions

func AddErrorSchemas

func AddErrorSchemas(gen *OAS)

AddErrorSchemas function is adding error schemas to the OpenAPI schema. It is defining and including error schemas such as "StatusError", "MissingRequiredFieldError", and corresponding responses like "BadRequest", "Unauthorized", "InternalServerError", and "Conflict" in the OpenAPI schema generation process. These error schemas and responses are used to document and handle different error scenarios that may occur in the API

func AddExamples

func AddExamples(gen *OAS)

AddExample is a function that adds an example to the OpenAPI schema. It takes a name and a value as parameters and creates a new example object with the provided value. The example is then added to the `Components.Examples` field of the `OAS` struct, making it available for use in the OpenAPI schema generation process

func AddHandlers

func AddHandlers(gen *OAS)

AddHandlers is a function that adds handlers to the OpenAPI schema. It takes a pointer to an `OAS` struct as a parameter and adds the following handlers to the `Components.Schemas` field of the `OAS` struct: `LoginRequest`, `LoginReply`, `ForgotPasswordRequest`, `ForgotPasswordReply`, `ResetPasswordRequest`, `ResetPasswordReply`, `RefreshRequest`, `RefreshReply`, `RegisterRequest`, `RegisterReply`, `ResendEmailRequest`, `ResendEmailReply`, `VerifyRequest`, `VerifyReply`, `SubscribeRequest`, and `SubscribeReply`. These handlers are used to define the request and response schemas for the API endpoints in the OpenAPI schema generation process

func AddParameters

func AddParameters(gen *OAS)

AddParameters is a function that adds parameters to the OpenAPI schema. It takes a pointer to an `OAS` struct as a parameter and adds the `TokenQuery` parameter to the `Components.Parameters` field of the `OAS` struct

Types

type OAS

type OAS struct {
	// Info provides metadata about the API
	Info openapi3.Info `json:"info,omitempty" yaml:"info,omitempty"`
	// Servers provides the base URL for the API
	Servers openapi3.Servers `json:"servers,omitempty" yaml:"servers,omitempty"`
	// Components provides reusable objects for the API
	Components openapi3.Components `json:"components,omitempty" yaml:"components,omitempty"`
	// Paths provides the available paths for the API
	Paths openapi3.Paths `json:"paths,omitempty" yaml:"paths,omitempty"`
	// Schemas provides reusable references to object schemas for the API
	Schemas openapi3.Schemas `json:"schemas,omitempty" yaml:"schemas,omitempty"`
	// Responses provides the available responses for the API
	Responses openapi3.Responses `json:"responses,omitempty" yaml:"responses,omitempty"`
	// Operation provides the available operations for the API
	Operation openapi3.Operation `json:"operation,omitempty" yaml:"operation,omitempty"`
	// Parameters provides the available parameters for the API
	Parameters openapi3.Parameters `json:"parameters,omitempty" yaml:"parameters,omitempty"`
	// Headers provides the available headers for the API
	Headers openapi3.Headers `json:"headers,omitempty" yaml:"headers,omitempty"`
	// SecuritySchemes provides the available security schemes for the API
	SecuritySchemes openapi3.SecuritySchemes `json:"securitySchemes,omitempty" yaml:"securitySchemes,omitempty"`
}

OAS is a helper struct to generate OpenAPI schema

func NewSchemaGenerator

func NewSchemaGenerator() *OAS

NewSchemaGenerator is a constructor function that creates a new instance of the `OAS` struct and initializes the `Paths`, `Components`, `Schemas`, `Responses`, `Operation`, `Parameters`, `Headers`, and `SecuritySchemes` fields of the struct. It then returns the newly created `OAS` struct

func (*OAS) AddExample

func (s *OAS) AddExample(name string, value interface{})

AddExample is a method of the `OAS` struct that is used to add an example to the OpenAPI schema

func (*OAS) AddHeader

func (s *OAS) AddHeader(name string, header *openapi3.Header)

AddHeader is a method of the `OAS` struct that is used to add a header to the OpenAPI schema. It takes a name for the header and a pointer to an `openapi3.Header` object as parameters. Inside the function, it adds the provided header to the `Components.Headers` field of the `OAS` struct, making it available for use in the OpenAPI schema generation process. This function allows you to define and include custom headers in your API documentation

func (*OAS) AddQueryParameter

func (s *OAS) AddQueryParameter(name string, value Parameter)

AddQueryParameter is a method of the `OAS` struct that is used to add a query parameter

func (*OAS) AddRequestBody

func (s *OAS) AddRequestBody(name string, body interface{})

AddRequestBody is used to add a request body to the OpenAPI schema - it takes a name for the request body and the body interface as parameters; it then creates a new request body object with a JSON schema reference and adds an example for the request body in the `application/json` content type

func (*OAS) AddResponse

func (s *OAS) AddResponse(name string, description string, ref string, example interface{})

AddResponse is used to add a response definition to the OpenAPI schema It takes parameters such as the name of the response, a description of the response, a reference to a schema, and an example of the response body

func (*OAS) AddSchema

func (s *OAS) AddSchema(name string, model interface{})

AddSchema is a method of the `OAS` struct that is used to add a schema to the OpenAPI schema

func (*OAS) AddSecurityScheme

func (s *OAS) AddSecurityScheme(name string, scheme *openapi3.SecurityScheme)

AddSecurityScheme adds a security scheme to the OAS

type Parameter

type Parameter struct {
	Name        string      `json:"name" yaml:"name"`
	Description string      `json:"description" yaml:"description"`
	Required    bool        `json:"required" yaml:"required"`
	Default     interface{} `json:"default" yaml:"default"`
	Type        string      `json:"type" yaml:"type"`
	In          string      `json:"in" yaml:"in"`
}

Parameter is a struct that represents a parameter in the OpenAPI schema