apiSpecDoc

Documentation

Index

• type ApiMethod
• type ApiSpecDoc
• type ExternalDoc
• type Group
  • func (g *Group) FindMethod(tp MethodType) *ApiMethod
• type MediaTypeObject
• type MethodType
• type Parameter
• type ParameterType
• type RequestBody
  • func (rb *RequestBody) FindContentByMediaType(mediaType string) *MediaTypeObject
• type Schema
  • func (sc *Schema) FindField(name string) *Schema
• type SchemaType
  • func ResolveSchemaType(strType string) SchemaType
• type Server
• type Type

Types

type ApiMethod

type ApiMethod struct {
	//Path to send request
	//For example /open/api/info/
	//It can contain path parameters,
	//They can be expressed with some placeholders like /api/v1/item/{id}/someth/{someth}
	//This placeholder definitions need to be searched as Parameters with Parameter.In equals ParameterType.Path
	Path string

	//Name of API method
	Name string

	//Description of API method if exists
	Description string

	//Type represents type of request method
	Type MethodType

	//RequestBody is a description of ApiMethod request body, nil if no request body
	RequestBody *RequestBody

	//Servers represent available paths for requests with description.
	//In the case of swagger we need to calculate it taking the deepest nested servers definition
	Servers []*Server

	//Parameters contains all possible request parameters
	//Including query, path, header and cookie parameters for the Open API
	//If Parameter.In is header - then it represents headers, if cookies - cookies,
	//so it's header and cookies full representation as well (not just a parametrisation)
	Parameters []*Parameter

	//ExternalDoc represents link to external method documentation (if exists)
	//
	ExternalDoc *ExternalDoc
}

ApiMethod represents particular API method to call

type ApiSpecDoc

type ApiSpecDoc struct {
	Title string

	Description string

	//Type of API definition
	//It's possible to be OpenApi, gRPC and others
	Type Type

	//Groups are just grouped lists of ApiMethod's , supposed to be displayed as folders
	//It relates to:
	//Tags - Open API specs
	//Services - RPCs
	Groups []*Group

	//Methods at the root level without groups
	Methods []*ApiMethod

	//Origin file hash sum
	Md5Sum string
}

ApiSpecDoc represents full API Specification document with all required data to view and execute requests Propose to not store something like components at the initial stage - leave it as update to simplify logic So each ApiMethod need to keep all schema (some duplication, but we could update it faster with extending of the model)

type ExternalDoc

type ExternalDoc struct {
	Description string

	//Url to external documentation about resource
	Url string
}

ExternalDoc may be available for the Open API And contain link to description of request method Maybe useful also for debugging - to find failed API description rapidly

type Group

type Group struct {
	//Name of the group
	Name string

	//Description of the group
	Description string

	//Methods is a set of request methods related to the group
	Methods []*ApiMethod
}

Group represents some grouping rule Tags for the open API Services for the gRPC

func (*Group) FindMethod

func (g *Group) FindMethod(tp MethodType) *ApiMethod

type MediaTypeObject

type MediaTypeObject struct {
	MediaType string
	Schema    *Schema
}

MediaTypeObject represents schema for the different media types i.e. "application/json" and etc.

type MethodType

type MethodType string

MethodType define type of action of the method

const (
	MethodConnect MethodType = "CONNECT"
	MethodGet     MethodType = "GET"
	MethodPut     MethodType = "PUT"
	MethodPost    MethodType = "POST"
	MethodDelete  MethodType = "DELETE"
	MethodOptions MethodType = "OPTIONS"
	MethodHead    MethodType = "HEAD"
	MethodPatch   MethodType = "PATCH"
	MethodTrace   MethodType = "TRACE"
)

type Parameter

type Parameter struct {
	Name string

	//In represents what part of request parameter relates
	//https://swagger.io/specification/#parameter-object
	In ParameterType

	Description string

	Schema *Schema

	//Required defines is parameter required
	Required bool
}

Parameter is abstraction of additional data to request It is headers for the REST API and metadata for the gRPC

type ParameterType

type ParameterType string

ParameterType represents to what part of request parameter relates

const (
	ParameterQuery  ParameterType = "query"
	ParameterHeader ParameterType = "header"
	ParameterPath   ParameterType = "path"
	ParameterCookie ParameterType = "cookie"
)

type RequestBody

type RequestBody struct {
	Description string

	//Content represents request object for the different media types
	Content []*MediaTypeObject

	//Required define is request body required
	Required bool
}

RequestBody is a representation of request body

func (*RequestBody) FindContentByMediaType

func (rb *RequestBody) FindContentByMediaType(mediaType string) *MediaTypeObject

type Schema

type Schema struct {
	//Key is a field name
	Key string

	//Type is a component field type
	//To provide some validation or specific input on UI
	Type SchemaType

	//Description of the field if exist
	Description string

	//Nested describe nested object/properties
	//If it's object and contain nested fields
	Fields []*Schema
}

Schema represents type or structure of request/response/metadata Also type, properties and description of the specific Schema field This is not the same as swagger schema!

General purpose of the Schema is to provide description for the UI how to generate sample method body for example. So it purpose to provide information to view to form sample request.

Schema focuses on description of json body structure (or parameter). Constraints supposed to be additional field in the schema.

For example object:

{
	"int_val": 5,
	"arr": [5, 6, 7, 8],
	"obj": {
		"field1": "test",
		"field2": "test2"
	}
}

can be expressed as:

dto.Schema{
	Type: dto.Object,
	Fields: []dto.Schema{
		{
			Key:  "int_val",
			Type: dto.Integer,
		},
		{
			Key: "arr",
			Type: dto.Array,
			Fields: []dto.Schema{
				{
					Type: dto.Integer,
				},
			},
		},
		{
			Key: "obj",
			Type: dto.Object,
			Fields: []dto.Schema{
				{
					Key: "field1",
					Type: dto.String,
				},
				{
					Key: "field2",
					Type: dto.String,
				},
			},
		},
	},
}

func (*Schema) FindField

func (sc *Schema) FindField(name string) *Schema

type SchemaType

type SchemaType string

SchemaType is the type of field.

const (
	Unknown    SchemaType = "UNKNOWN"
	NotDefined SchemaType = "NOT_DEFINED"
	Integer    SchemaType = "INTEGER"
	Boolean    SchemaType = "BOOLEAN"
	Number     SchemaType = "NUMBER"
	String     SchemaType = "STRING"
	Date       SchemaType = "DATE"
	Array      SchemaType = "ARRAY"  //Array type may contain a single nested field with a type to define the full array type
	Map        SchemaType = "MAP"    //Map i.e. { "map_name": {"key1":"value1", "key2":"value2"}}
	OneOf      SchemaType = "ONE_OF" //OneOf is one of the different types (C union) (from nested fields)
	AnyOf      SchemaType = "ANY_OF" //AnyOf defines that the result object can contain any set of sub-schemes
	AllOf      SchemaType = "ALL_OF" //AllOf defines that the result object combines all listed objects/properties.
	Not        SchemaType = "NOT"    //Not represents a type that can't be used. So it's possible to use any of the types except "not"
	Object     SchemaType = "OBJECT" //Object represents the object and contains a set of fields inside
)

func ResolveSchemaType

func ResolveSchemaType(strType string) SchemaType

type Server

type Server struct {
	//Url to access server (no templates, real url)
	Url string

	//Description of the particular server (relates to Open API spec)
	Description string
}

Server represents server description To use in the address line of view https://swagger.io/specification/#server-object

type Type

type Type int

Type represents type of parsed API

const (
	TypeOpenApi Type = iota
)