apido

README

GoLang Swagger API docs generator

Documentation

Index

• func CheckReq(methodParams []InParam, reqParams map[string]string) (map[string]interface{}, map[string]ValidCond)
• func ToSwag(val interface{}) map[string]*InParam
• type ApiDefinition
• type ApiInfo
• type ApiMethod
• type ApiPaths
• type ApiResponse
• type ApiSchema
• type ApiSpec
  • func (tmpApiSpec *ApiSpec) AppendDef(myDefinition string, myTitle string, myObj interface{})
  • func (tmpApiSpec *ApiSpec) AppendPath(apiPath string, reqType string, summary string, description string, ...)
• type ApiVerbs
• type InParam
  • func (inp *InParam) IsMatchValue(val string, isValExists bool) (interface{}, ValidCond)
• type ScrRequirement
• type SecurityScheme
• type ValidCond
  • func (validCond *ValidCond) IsValidated() bool

Examples

• CheckReq
• ToSwag

Functions

func CheckReq

func CheckReq(methodParams []InParam, reqParams map[string]string) (map[string]interface{}, map[string]ValidCond)

CheckReq check input params of request (url or body) and params of method If params doesnt match - return errors as a map methodParams: [{in:form, name:my_param, description:super, format:int16}] reqParams {my_param:req_value1, other_param: req_value2}

Example

methodParams: [{in:form, name:my_param, description:super, format:int16}] reqParams {my_param:req_value1, other_param: req_value2}

demoMethodParams := []InParam{
	InParam{
		In:          "formData",
		Name:        "demoparam",
		Description: "Demo parameter",
		SwagType:    "integer",
		SwagFormat:  "int16",
		Required:    false,
	},
	InParam{
		In:          "query",
		Name:        "demobool",
		Description: "Demo boolean",
		SwagType:    "boolean",
		Required:    false,
	},
	InParam{
		In:          "query",
		Name:        "demostring",
		Description: "Demo string value",
		SwagType:    "string",
		Required:    false,
	},
}

demoReqParams := map[string]string{
	"demoparam":  "1234",
	"demobool":   "true",
	"demostring": "",
}

result, conds := CheckReq(demoMethodParams, demoReqParams)

fmt.Println(conds)

fmt.Println(result["demoparam"])
fmt.Println(result["demobool"])

Output:
map[]
1234
true

func ToSwag

func ToSwag(val interface{}) map[string]*InParam

ToSwag converts params to swag format

Example

package main

import (
	"fmt"
)

type SomeThing struct {
	IsImportant bool `json:"is_important" summary:"maybe"`
}

// serv_group with locale
type DemoStruct struct {
	Id           int32        `json:"id" summary:"unique number"`
	Name         string       `json:"name" summary:"name of object"`
	ArrSomeThing []*SomeThing `json:"arr_some_thing" summary:"array of some things"`
	OptProp      *string      `json:"opt_prop" summary:"Optional property"`

	OptInt          *int32       `json:"opt_int"`
	ItemUnderStruct *UnderStruct `json:"under_struct"`
}

type UnderStruct struct {
	VeryProp string `json:"very_prop" summary:"Very"`
}

func main() {

	result := ToSwag(DemoStruct{})

	fmt.Println(result["id"].SwagType)
	fmt.Println(result["id"].SwagFormat)
	fmt.Println(result["name"].SwagType)
	fmt.Println(result["arr_some_thing"].SwagType)
	// name convention for child elements: arr_child_name
	fmt.Println(result["arr_some_thing"].ArrItem.RefParam)

	fmt.Println("==opt_prop==")
	fmt.Println(result["opt_prop"].SwagType)

	fmt.Println("==opt_int==")
	fmt.Println(result["opt_int"].SwagType)
	fmt.Println(result["opt_int"].SwagFormat)

	fmt.Println("==under_struct==")
	fmt.Println(result["under_struct"].RefParam)

}

Output:
integer
int32
string
array
some_thing
==opt_prop==
string
==opt_int==
integer
int32
==under_struct==
under_struct

Types

type ApiDefinition

type ApiDefinition struct {
	// required properties as one array
	Title      string              `json:"title,omitempty"`
	Required   []string            `json:"required,omitempty"`
	Properties map[string]*InParam `json:"properties,omitempty"`
}

type ApiInfo

type ApiInfo struct {
	Title          string            `json:"title"`
	Description    string            `json:"description,omitempty"`
	TermsOfService string            `json:"termsOfService,omitempty"`
	Contact        map[string]string `json:"contact,omitempty"`
	Version        string            `json:"version"`
	License        map[string]string `json:"license,omitempty"`
}

ApiInfo https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#info-object

type ApiMethod

type ApiMethod struct {
	Tags []string `json:"tags,omitempty"`
	// this field SHOULD be less than 120 characters.
	Summary     string                 `json:"summary,omitempty"`
	Description string                 `json:"description"`
	OperationId string                 `json:"operationId,omitempty"`
	Consumes    []string               `json:"consumes,omitempty"`
	Produces    []string               `json:"produces,omitempty"`
	Parameters  []InParam              `json:"parameters,omitempty"`
	Responses   map[string]ApiResponse `json:"responses,omitempty"`
	Deprecated  bool                   `json:"deprecated,omitempty"`
	Security    []ScrRequirement       `json:"security,omitempty"`
}

type ApiPaths

type ApiPaths map[string]ApiVerbs

ApiPath: { "/master/getById": { ...}, "/rubric/getNext": {..}}

type ApiResponse

type ApiResponse struct {
	Description string    `json:"description"`
	Schema      ApiSchema `json:"schema,omitempty"`
}

type ApiSchema

type ApiSchema struct {

	// All titles and description - in RefStr
	RefStr string `json:"$ref,omitempty"`
}

ApiSchema - definition of input and output data types "type": "array",items": {"$ref": "#/definitions/pet" }, "$ref": "someref" http://json-schema.org/example1.html

type ApiSpec

type ApiSpec struct {
	Swagger  string   `json:"swagger"`
	Host     string   `json:"host"`
	Info     ApiInfo  `json:"info"`
	BasePath string   `json:"basePath"`
	Schemes  []string `json:"schemes"`
	Consumes []string `json:"consumes"`
	Produces []string `json:"produces"`

	Paths               ApiPaths                  `json:"paths""`
	Definitions         map[string]ApiDefinition  `json:"definitions,omitempty"`
	SecurityDefinitions map[string]SecurityScheme `json:"securityDefinitions,omitempty"`
	// A declaration of which security schemes are applied for the API as a whole.
	// The list of values describes alternative security schemes
	//   that can be used (that is, there is a logical OR between the security
	//   requirements). Individual operations can override this definition.
	// "security": [{"petstore_auth": ["write:pets","read:pets"]}]
	Security []ScrRequirement `json:"security,omitempty"`
}

func (*ApiSpec) AppendDef

func (tmpApiSpec *ApiSpec) AppendDef(myDefinition string,
	myTitle string,
	myObj interface{})

func (*ApiSpec) AppendPath

func (tmpApiSpec *ApiSpec) AppendPath(apiPath string,
	reqType string,
	summary string,
	description string,
	apiTags []string,
	consumes []string,
	produces []string,
	inParamArr []InParam,
	respMap map[string]ApiResponse)

type ApiVerbs

type ApiVerbs map[string]ApiMethod

ApiVerb: { "get": {...}, "post":...}

type InParam

type InParam struct {
	Name        string `json:"name,omitempty"`
	In          string `json:"in,omitempty"`
	Description string `json:"description,omitempty"`
	Required    bool   `json:"required,omitempty"`
	// The value "type" MUST be one of
	// "string", "number", "integer", "boolean", "array" or "file".
	// If type is "file", the consumes MUST be either "multipart/form-data"
	// or " application/x-www-form-urlencoded" and the parameter MUST be in "formData".
	SwagType string   `json:"type,omitempty"`
	ArrItem  *InParam `json:"items,omitempty"`
	RefParam string   `json:"$ref,omitempty"`
	// Props and AddtProps doesnt work in UI
	//Props  map[string]InParam   `json:"properties,omitempty"`
	//AddtProps  map[string]string   `json:"additionalProperties,omitempty"`
	// https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#dataTypeFormat
	// int32, int64, float, double, byte
	SwagFormat       string `json:"format,omitempty"`
	Maximum          int32  `json:"maximum,omitempty"`
	Minimum          int32  `json:"minimum,omitempty"`
	ExclusiveMaximum bool   `json:"exclusiveMaximum,omitempty"`
	ExclusiveMinimum bool   `json:"exclusiveMinimum,omitempty"`
	MinLength        int32  `json:"minLength,omitempty"`
	MaxLength        int32  `json:"maxLength,omitempty"`
	Pattern          string `json:"pattern,omitempty"`
}

InParam describes a single operation parameter http://json-schema.org/latest/json-schema-validation.html https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#parameter-object

func (*InParam) IsMatchValue

func (inp *InParam) IsMatchValue(val string, isValExists bool) (interface{}, ValidCond)

IsMatchValue checks a value from a request (from url or body) Return unmatched properties, like { unmatched: { valType: { our: string, yours: integer }, maxLength: { our: 10, yours: 20 }, minLength: { our: 2, yours: 0 }, required: { our: true, yours: false }} Rerun ourValue, converted to required SwagType If val is not exists - empty string "" You can not use outValue if ValidConditions is not empty

type ScrRequirement

type ScrRequirement map[string][]string

ScrRequirement - security requirement. https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#securityRequirementObject

type SecurityScheme

type SecurityScheme struct {
	ScrType string `json:"type"`
	Name    string `json:"name,omitempty"`
	In      string `json:"in,omitempty"`
}

SecurityScheme https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#securityDefinitionsObject Supported schemes are basic authentication, an API key

(either as a header or as a query parameter) and OAuth2's common flows
(implicit, password, application and access code).

type ValidCond

type ValidCond struct {
	UnMatched map[string]string `json:"conditions,omitempty"`
}

ValidCond

func (*ValidCond) IsValidated

func (validCond *ValidCond) IsValidated() bool

IsValidated Quick property to identify errors instead len(array)