jsonmsg

README

jsonmsg

A Go package that parses API specs to generate server/client source code in any supported language

Features

• Parses spec documents based on https://github.com/jsonmsg/spec
• Generates source code for any supported language (currently only Go/server)
• Test suite with shared schema fixtures
• Library and standalone compiler binary jsonmsgc

GoDoc

Godoc is available from https://godoc.org/github.com/tfkhsr/jsonmsg.

Install

To install as library run:

go get -u github.com/tfkhsr/jsonmsg

To install the standalone compiler binary jsonmsgc run:

go get -u github.com/tfkhsr/jsonmsg/cmd/jsonmsgc

Documentation

Overview

Package jsonmsg parses API specs. The resulting spec can be used to generate server/client source code in any supported language.

The jsonmsg implementation is based on https://github.com/jsonmsg/spec with the meta-schema https://github.com/jsonmsg/spec/blob/master/meta.json

Generators

go: https://godoc.org/github.com/tfkhsr/jsonmsg/golang

Parse a spec:

schema := `
{
  "endpoints": {
    "http": "https://jsonmsg.github.io/v1",
    "websocket": "wss://jsonmsg.github.io/v1"
  },
  "messages": {
    "findUser": {
      "in": "#/definitions/userQuery",
      "outs": [
        "#/definitions/user",
        "#/definitions/error"
      ],
      "group": "user"
    }
  },
  "definitions": {
    "user": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "name": {
          "type": "string"
        }
      },
      "required": ["id", "name"]
    },
    "userQuery": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        }
      },
      "required": ["id"]
    },
    "error": {
      "type": "object",
      "properties": {
        "message": {
          "type": "string"
        }
      },
    "required": ["message"]
    }
  }
}
`

// parse spec
spc, err := Parse(spec)
if err != nil {
	panic(err)
}

// spc now contains:
// spc.Messages["findUser"]        : *Message{...}
// spc.Definitions["user"]         : *jsonschema.Schema{...}

Index

• type Message
  • func (m *Message) NewInstance() (interface{}, error)
• type Spec
  • func Parse(b []byte) (*Spec, error)
  • func (s *Spec) HTTPSpec() ([]byte, error)
  • func (s *Spec) JSONSpec() ([]byte, error)

Examples

• Message.NewInstance
• Parse

Types

type Message

type Message struct {
	// Short description
	Title string

	// Detailed description
	Description string

	// Literal message name as defined in spec
	Msg string

	// Camel-Cased name
	Name string

	// JSON Pointer to input schema
	In string

	// JSON Pointers to possible output schemas
	Outs []string

	// Pointer to parsed input schema
	InSchema *jsonschema.Schema

	// Pointers to parsed output schemas
	OutSchemas []*jsonschema.Schema

	// Pointer to parent spec
	Spec *Spec

	// Optional: Group name associating message to spec.GroupedMessages
	Group string
}

A Message holds details about name, in- and out parameters

func (*Message) NewInstance

func (m *Message) NewInstance() (interface{}, error)

Creates a new message instance conforming to the message schema

Example

Generate a sample message conforming to the specified message schema

schema := `
{
	"endpoints": {
		"http": "https://jsonmsg.github.io/v1",
		"websocket": "wss://jsonmsg.github.io/v1"
	},
	"messages": {
		"findUser": {
			"in": "#/definitions/userQuery",
			"outs": [
				"#/definitions/user",
				"#/definitions/error"
			],
			"group": "user"
		}
	},
	"definitions": {
		"user": {
			"type": "object",
			"properties": {
				"id": {
					"type": "string"
				},
				"name": {
					"type": "string"
				}
			},
			"required": ["id", "name"]
		},
		"userQuery": {
			"type": "object",
			"properties": {
				"id": {
					"type": "string"
				}
			},
			"required": ["id"]
		},
		"error": {
			"type": "object",
			"properties": {
				"message": {
					"type": "string"
				}
			},
			"required": ["message"]
		}
	}
}
`

// parse into spec
spec, err := Parse([]byte(schema))
if err != nil {
	panic(err)
}

// create go instance
inst, err := spec.Messages["findUser"].NewInstance()
if err != nil {
	panic(err)
}

// marshal to json
raw, err := json.MarshalIndent(inst, "", "  ")
if err != nil {
	panic(err)
}

fmt.Printf("%s\n", raw)

Output:

{
  "data": {
    "id": "string"
  },
  "msg": "findUser"
}

type Spec

type Spec struct {
	// General title of API
	Title string

	// Further information
	Description string

	// Map of protocols to URLs (urlString embeds url.URL for unmarshaling)
	Endpoints map[string]*urlString

	// Map of message names to Messages
	Messages map[string]*Message

	// Map of groups of message names to Messages
	GroupedMessages map[string]map[string]*Message

	// JSON Schema definitions for data definition
	Definitions jsonschema.Index `json:"-"`

	// Raw spec
	Raw []byte
}

A Spec holds endpoints, messages and definitions of an API. Parsed spec must validate against meta-schema https://github.com/jsonmsg/spec/blob/master/meta.json

func Parse

func Parse(b []byte) (*Spec, error)

Parses a raw schema into a Spec

Example

Parse a schema into an Index of Schemas

schema := `
{
	"endpoints": {
		"http": "https://jsonmsg.github.io/v1",
		"websocket": "wss://jsonmsg.github.io/v1"
	},
	"messages": {
		"findUser": {
			"in": "#/definitions/userQuery",
			"outs": [
				"#/definitions/user",
				"#/definitions/error"
			],
			"group": "user"
		}
	},
	"definitions": {
		"user": {
			"type": "object",
			"properties": {
				"id": {
					"type": "string"
				},
				"name": {
					"type": "string"
				}
			},
			"required": ["id", "name"]
		},
		"userQuery": {
			"type": "object",
			"properties": {
				"id": {
					"type": "string"
				}
			},
			"required": ["id"]
		},
		"error": {
			"type": "object",
			"properties": {
				"message": {
					"type": "string"
				}
			},
			"required": ["message"]
		}
	}
}
`

// parse into index
spec, err := Parse([]byte(schema))
if err != nil {
	panic(err)
}

fmt.Printf("findUser name: %s\n", spec.Messages["findUser"].Name)
fmt.Printf("findUser in name: %s\n", spec.Messages["findUser"].InSchema.Name)
fmt.Printf("findUser in group: %s\n", spec.GroupedMessages["user"]["findUser"].InSchema.Name)

Output:

findUser name: FindUser
findUser in name: UserQuery
findUser in group: UserQuery

func (*Spec) HTTPSpec

func (s *Spec) HTTPSpec() ([]byte, error)

Returns an HTML website version of the spec that must be served on {{ BaseURL }}/spec by servers

func (*Spec) JSONSpec

func (s *Spec) JSONSpec() ([]byte, error)

Returns an indented, marshalled version of the spec that must be served on {{ BaseURL }}/spec.json by servers