summerfish

README

SummerFish

A refreshing way of handling swagger docs in Golang. Automatic documentation has arrived.

Description

With SummerFish we bring to Go developers a way of having swagger documentation auto-generated with no annotations needed!

This package contains a golang implementation of Swagger 2.0 (aka OpenAPI 2.0): it knows how to serialize and deserialize swagger specifications.

Swagger is a simple yet powerful representation of your RESTful API.

Features

summerfish-swagger brings to the go community a way of generating swagger documentation without needing any annotations or changes on the your code. It is also integrated with the Swagger UI to help you serving as one endpoint.

Example

You can check our live server docs at https://plicca.com/armadillo/docs/

Check out the example package to test with a minimum code example.

Project status

summerfish-swagger is still very early in its life.

Future features

• Support more routers (currently we only support gorrila mux)
• Increase test coverage
• Your suggestion here :)

Help us out

Like this project? Feel free to create an issue, develop a new feature and contribute in any way to this project

Documentation

Index

• func RemoveCommentSection(line string) (string, bool)
• type Config
• type InputParameter
• type Method
• type NameType
• type Operation
• type OperationResponse
• type PathsHolder
• type RouteHolder
  • func GetInfoFromRouter(r *mux.Router) (holders []RouteHolder, err error)
• type RouteParser
• type RouteParserHolder
• type RoutePath
• type SchemaParameters
• type SchemeHolder
  • func (s *SchemeHolder) GenerateSwaggerJson(routes []RouteHolder, filePath string) (err error)
  • func (s *SchemeHolder) GenerateSwaggerYaml(routes []RouteHolder, filePath string) (err error)
• type SchemeInformation

Functions

func RemoveCommentSection

func RemoveCommentSection(line string) (string, bool)

Types

type Config

type Config struct {
	Schemes                []string
	SwaggerFilePath        string
	SwaggerFileRoute       string
	SwaggerFileHeaderRoute string
	SwaggerUIRoute         string
	BaseRoute              string
}

type InputParameter

type InputParameter struct {
	Type        string           `json:"type,omitempty" yaml:"type,omitempty"`
	Name        string           `json:"name"`
	Description string           `json:"description"`
	QueryType   string           `json:"in" yaml:"in"`
	Schema      SchemaParameters `json:"schema,omitempty" yaml:"schema,omitempty"`
	Required    bool             `json:"required,omitempty" yaml:"required,omitempty"`
}

type Method

type Method map[string]Operation

type NameType

type NameType struct {
	Name       string
	Type       string
	IsArray    bool
	Children   []NameType
	IsRequired bool
}

type Operation

type Operation struct {
	Parameters []InputParameter             `json:"parameters"`
	ID         string                       `json:"operationId" yaml:"operationId"`
	Summary    string                       `json:"summary"`
	Tags       []string                     `json:"tags"`
	Responses  map[string]OperationResponse `json:"responses"`
	Consumes   []string                     `json:"consumes,omitempty" yaml:"consumes,omitempty"`
}

type OperationResponse

type OperationResponse struct {
	Description string `json:"description,omitempty" yaml:"description,omitempty"`
}

type PathsHolder

type PathsHolder map[string]Method

type RouteHolder

type RouteHolder struct {
	ID       int
	Path     []NameType
	Query    []NameType
	Body     NameType
	FormData []NameType
	Route    string
	Methods  []string
	Name     string
}

func GetInfoFromRouter

func GetInfoFromRouter(r *mux.Router) (holders []RouteHolder, err error)

type RouteParser

type RouteParser struct {
	ID                   int
	Route                string
	RelativePath         string
	FullPath             string
	LineNumber           int
	Methods              []string
	IsOnlyEndpointParser bool
}

type RouteParserHolder

type RouteParserHolder struct {
	ID int
	// contains filtered or unexported fields
}

type RoutePath

type RoutePath struct {
	RelativePath string
	FullPath     string
	LineNumber   int
}

type SchemaParameters

type SchemaParameters struct {
	Type       string                      `json:"type"`
	Items      *SchemaParameters           `json:"items,omitempty" yaml:"items,omitempty"`
	Properties map[string]SchemaParameters `json:"properties,omitempty" yaml:"properties,omitempty"`
}

type SchemeHolder

type SchemeHolder struct {
	SwaggerVersion string            `json:"swagger" yaml:"swagger"`
	Information    SchemeInformation `json:"info" yaml:"info"`
	Host           string            `json:"host,omitempty" yaml:"host,omitempty"`
	BasePath       string            `json:"basePath" yaml:"basePath"`
	Schemes        []string          `json:"schemes"`
	Paths          PathsHolder       `json:"paths"`
}

func (*SchemeHolder) GenerateSwaggerJson

func (s *SchemeHolder) GenerateSwaggerJson(routes []RouteHolder, filePath string) (err error)

func (*SchemeHolder) GenerateSwaggerYaml

func (s *SchemeHolder) GenerateSwaggerYaml(routes []RouteHolder, filePath string) (err error)

type SchemeInformation

type SchemeInformation struct {
	Version string `json:"version,omitempty" yaml:"version,omitempty"`
	Title   string `json:"title,omitempty" yaml:"title,omitempty"`
}