genschema

Documentation

Overview

Package genschema provides a generator for the JSON schema controller. The schema controller responds to GET /schema requests with the API JSON Hyper-schema. This JSON schema can be used to generate API documentation, ruby and Go API clients. See the blog post (https://blog.heroku.com/archives/2014/1/8/json_schema_for_heroku_platform_api) describing how Heroku leverages the JSON Hyper-schema standard (http://json-schema.org/latest/json-schema-hypermedia.html) for more information.

Index

• Constants
• Variables
• func Generate() (files []string, err error)
• func GenerateMediaTypeDefinition(api *design.APIDefinition, mt *design.MediaTypeDefinition, view string)
• func GenerateResourceDefinition(api *design.APIDefinition, r *design.ResourceDefinition)
• func GenerateTypeDefinition(api *design.APIDefinition, ut *design.UserTypeDefinition)
• func MediaTypeRef(api *design.APIDefinition, mt *design.MediaTypeDefinition, view string) string
• func TypeRef(api *design.APIDefinition, ut *design.UserTypeDefinition) string
• type Generator
  • func NewGenerator(options ...Option) *Generator
  • func (g *Generator) Cleanup()
  • func (g *Generator) Generate() (_ []string, err error)
• type JSONLink
• type JSONMedia
• type JSONSchema
  • func APISchema(api *design.APIDefinition) *JSONSchema
  • func NewJSONSchema() *JSONSchema
  • func TypeSchema(api *design.APIDefinition, t design.DataType) *JSONSchema
  • func (s *JSONSchema) Dup() *JSONSchema
  • func (s *JSONSchema) JSON() ([]byte, error)
  • func (s *JSONSchema) Merge(other *JSONSchema)
• type JSONType
• type Option
  • func API(API *design.APIDefinition) Option
  • func OutDir(outDir string) Option

Constants

const (
	// JSONArray represents a JSON array.
	JSONArray JSONType = "array"
	// JSONBoolean represents a JSON boolean.
	JSONBoolean = "boolean"
	// JSONInteger represents a JSON number without a fraction or exponent part.
	JSONInteger = "integer"
	// JSONNumber represents any JSON number. Number includes integer.
	JSONNumber = "number"
	// JSONNull represents the JSON null value.
	JSONNull = "null"
	// JSONObject represents a JSON object.
	JSONObject = "object"
	// JSONString represents a JSON string.
	JSONString = "string"
	// JSONFile is an extension used by Swagger to represent a file download.
	JSONFile = "file"
)

const SchemaRef = "http://json-schema.org/draft-04/hyper-schema"

SchemaRef is the JSON Hyper-schema standard href.

Variables

var (
	// Definitions contains the generated JSON schema definitions
	Definitions map[string]*JSONSchema
)

Functions

func Generate

func Generate() (files []string, err error)

Generate is the generator entry point called by the meta generator.

func GenerateMediaTypeDefinition

func GenerateMediaTypeDefinition(api *design.APIDefinition, mt *design.MediaTypeDefinition, view string)

GenerateMediaTypeDefinition produces the JSON schema corresponding to the given media type and given view.

func GenerateResourceDefinition

func GenerateResourceDefinition(api *design.APIDefinition, r *design.ResourceDefinition)

GenerateResourceDefinition produces the JSON schema corresponding to the given API resource. It stores the results in cachedSchema.

func GenerateTypeDefinition

func GenerateTypeDefinition(api *design.APIDefinition, ut *design.UserTypeDefinition)

GenerateTypeDefinition produces the JSON schema corresponding to the given type.

func MediaTypeRef

func MediaTypeRef(api *design.APIDefinition, mt *design.MediaTypeDefinition, view string) string

MediaTypeRef produces the JSON reference to the media type definition with the given view.

func TypeRef

func TypeRef(api *design.APIDefinition, ut *design.UserTypeDefinition) string

TypeRef produces the JSON reference to the type definition.

Types

type Generator

type Generator struct {
	API    *design.APIDefinition // The API definition
	OutDir string                // Path to output directory
	// contains filtered or unexported fields
}

Generator is the application code generator.

func NewGenerator

func NewGenerator(options ...Option) *Generator

NewGenerator returns an initialized instance of a JavaScript Client Generator

func (*Generator) Cleanup

func (g *Generator) Cleanup()

Cleanup removes all the files generated by this generator during the last invokation of Generate.

func (*Generator) Generate

func (g *Generator) Generate() (_ []string, err error)

Generate produces the skeleton main.

type JSONLink

type JSONLink struct {
	Title        string      `json:"title,omitempty"`
	Description  string      `json:"description,omitempty"`
	Rel          string      `json:"rel,omitempty"`
	Href         string      `json:"href,omitempty"`
	Method       string      `json:"method,omitempty"`
	Schema       *JSONSchema `json:"schema,omitempty"`
	TargetSchema *JSONSchema `json:"targetSchema,omitempty"`
	MediaType    string      `json:"mediaType,omitempty"`
	EncType      string      `json:"encType,omitempty"`
}

JSONLink represents a "link" field in a JSON hyper schema.

type JSONMedia

type JSONMedia struct {
	BinaryEncoding string `json:"binaryEncoding,omitempty"`
	Type           string `json:"type,omitempty"`
}

JSONMedia represents a "media" field in a JSON hyper schema.

type JSONSchema

type JSONSchema struct {
	Schema string `json:"$schema,omitempty"`
	// Core schema
	ID           string                 `json:"id,omitempty"`
	Title        string                 `json:"title,omitempty"`
	Type         JSONType               `json:"type,omitempty"`
	Items        *JSONSchema            `json:"items,omitempty"`
	Properties   map[string]*JSONSchema `json:"properties,omitempty"`
	Definitions  map[string]*JSONSchema `json:"definitions,omitempty"`
	Description  string                 `json:"description,omitempty"`
	DefaultValue interface{}            `json:"default,omitempty"`
	Example      interface{}            `json:"example,omitempty"`

	// Hyper schema
	Media     *JSONMedia  `json:"media,omitempty"`
	ReadOnly  bool        `json:"readOnly,omitempty"`
	PathStart string      `json:"pathStart,omitempty"`
	Links     []*JSONLink `json:"links,omitempty"`
	Ref       string      `json:"$ref,omitempty"`

	// Validation
	Enum                 []interface{} `json:"enum,omitempty"`
	Format               string        `json:"format,omitempty"`
	Pattern              string        `json:"pattern,omitempty"`
	Minimum              *float64      `json:"minimum,omitempty"`
	Maximum              *float64      `json:"maximum,omitempty"`
	MinLength            *int          `json:"minLength,omitempty"`
	MaxLength            *int          `json:"maxLength,omitempty"`
	MinItems             *int          `json:"minItems,omitempty"`
	MaxItems             *int          `json:"maxItems,omitempty"`
	Required             []string      `json:"required,omitempty"`
	AdditionalProperties bool          `json:"additionalProperties,omitempty"`

	// Union
	AnyOf []*JSONSchema `json:"anyOf,omitempty"`
}

JSONSchema represents an instance of a JSON schema. See http://json-schema.org/documentation.html

func APISchema

func APISchema(api *design.APIDefinition) *JSONSchema

APISchema produces the API JSON hyper schema.

func NewJSONSchema

func NewJSONSchema() *JSONSchema

NewJSONSchema instantiates a new JSON schema.

func TypeSchema

func TypeSchema(api *design.APIDefinition, t design.DataType) *JSONSchema

TypeSchema produces the JSON schema corresponding to the given data type.

func (*JSONSchema) Dup

func (s *JSONSchema) Dup() *JSONSchema

Dup creates a shallow clone of the given schema.

func (*JSONSchema) JSON

func (s *JSONSchema) JSON() ([]byte, error)

JSON serializes the schema into JSON. It makes sure the "$schema" standard field is set if needed prior to delegating to the standard JSON marshaler.

func (*JSONSchema) Merge

func (s *JSONSchema) Merge(other *JSONSchema)

Merge does a two level deep merge of other into s.

type JSONType

type JSONType string

JSONType is the JSON type enum.

type Option

type Option func(*Generator)

Option a generator option definition

func API

func API(API *design.APIDefinition) Option

API The API definition

func OutDir

func OutDir(outDir string) Option

OutDir Path to output directory