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(api *design.APIDefinition) ([]string, error)
• func GenerateMediaTypeDefinition(api *design.APIDefinition, mt *design.MediaTypeDefinition)
• func GenerateResourceDefinition(api *design.APIDefinition, r *design.ResourceDefinition)
• func GenerateTypeDefinition(api *design.APIDefinition, ut *design.UserTypeDefinition)
• func JSONSchemaDir() string
• func MediaTypeRef(api *design.APIDefinition, mt *design.MediaTypeDefinition) string
• func TypeRef(api *design.APIDefinition, ut *design.UserTypeDefinition) string
• type Command
  • func NewCommand() *Command
  • func (c *Command) RegisterFlags(r codegen.FlagRegistry)
  • func (c *Command) Run() ([]string, error)
• type Generator
  • func NewGenerator() (*Generator, error)
  • func (g *Generator) Cleanup()
  • func (g *Generator) Generate(api *design.APIDefinition) (_ []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

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"
)

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
)

var ServiceURL string

ServiceURL is used to build the JSON schema ID of the root document.

Functions

func Generate

func Generate(api *design.APIDefinition) ([]string, error)

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

func GenerateMediaTypeDefinition

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

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

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 JSONSchemaDir

func JSONSchemaDir() string

JSONSchemaDir is the path to the directory where the schema controller is generated.

func MediaTypeRef

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

MediaTypeRef produces the JSON reference to the media type definition.

func TypeRef

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

TypeRef produces the JSON reference to the type definition.

Types

type Command

type Command struct {
	*codegen.BaseCommand
}

Command is the goa application code generator command line data structure. It implements meta.Command.

func NewCommand

func NewCommand() *Command

NewCommand instantiates a new command.

func (*Command) RegisterFlags

func (c *Command) RegisterFlags(r codegen.FlagRegistry)

RegisterFlags registers the command line flags with the given registry.

func (*Command) Run

func (c *Command) Run() ([]string, error)

Run simply calls the meta generator.

type Generator

type Generator struct {
	// contains filtered or unexported fields
}

Generator is the application code generator.

func NewGenerator

func NewGenerator() (*Generator, error)

NewGenerator returns the application code 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(api *design.APIDefinition) (_ []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:"defaultValue,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"`
	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.