raml

package module
v0.0.0-...-31db66e Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 8, 2016 License: BSD-2-Clause-Views Imports: 9 Imported by: 5

README

raml

An implementation of a RAML parser for Go. Compliant with RAML 0.8.

Introduction

RAML is a YAML-based language that describes RESTful APIs. Together with the YAML specification, this specification provides all the information necessary to describe RESTful APIs; to create API client-code and API server-code generators; and to create API user documentation from RAML API definitions.

The raml package enables Go programs to parse RAML files and valid RAML API definitions. It was originally developed within EverythingMe.

Status

The raml package is currently unstable and does not offer any kind of API stability guarantees.

Installation

The yaml package may be installed by running:

$ go get gopkg.in/raml.v0

Opening that same URL in a browser will present a nice introductory page containing links to the documentation, source code, and all versions available for the given package:

https://gopkg.in/raml.v0

The actual implementation of the package is in GitHub:

https://github.com/go-raml/raml

Contributing to development

Typical installation process for developing purposes:

$ git clone git@github.com:go-raml/raml.git
$ cd raml
$ go build
$ go install
$ go test

Usage

Usage is very simple:

package main

import (
	"fmt"
	raml "gopkg.in/raml.v0"
	"github.com/kr/pretty"
)

func main() {

	fileName := "./samples/congo/api.raml"

	if apiDefinition, err := raml.ParseFile(fileName); err != nil {
		fmt.Printf("Failed parsing RAML file %s:\n  %s", fileName, err.Error())
	} else {
		fmt.Printf("Successfully parsed RAML file %s!\n\n", fileName)
		pretty.Printf(apiDefinition)
	}
}

Getting help

Roadmap

TBD.

Reporting Bugs and Contributing Code

  • Want to report a bug or request a feature? Please open an issue.
  • Want to contribute to raml? Fork the project and make a pull request. Cool cool cool.

License

See LICENSE file.

Documentation

Overview

This package contains the parser, validator and types that implement the RAML specification, as documented here: http://raml.org/spec.html

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func PostProcess 

func PostProcess(d *APIDefinition)

Types

type APIDefinition 

type APIDefinition struct {

	// RAML 0.8
	RAMLVersion string `yaml:"raml_version"`

	// The title property is a short plain text description of the RESTful API.
	// The title property's value SHOULD be suitable for use as a title for the
	// contained user documentation
	Title string `yaml:"title"`

	// If RAML API definition is targeted to a specific API version, it should
	// be noted here
	Version string `yaml:"version"`

	// A RESTful API's resources are defined relative to the API's base URI.
	// If the baseUri value is a Level 1 Template URI, the following reserved
	// base URI parameters are available for replacement:
	//
	// version - The content of the version field.
	BaseUri string `yaml:"baseUri"`

	// A resource or a method can override a base URI template's values.
	// This is useful to restrict or change the default or parameter selection
	// in the base URI. The baseUriParameters property MAY be used to override
	// any or all parameters defined at the root level baseUriParameters
	// property, as well as base URI parameters not specified at the root level.
	// In a resource structure of resources and nested resources with their
	// methods, the most specific baseUriParameter fully overrides any
	// baseUriParameter definition made before
	BaseUriParameters map[string]NamedParameter `yaml:"baseUriParameters"`

	// Level 1 URI custom parameters, which are useful in a variety of scenario.
	// URI parameters can be further defined by using the uriParameters
	// property. The use of uriParameters is OPTIONAL. The uriParameters
	// property MUST be a map in which each key MUST be the name of the URI
	// parameter as defined in the baseUri property. The uriParameters CANNOT
	// contain a key named version because it is a reserved URI parameter name.
	UriParameters map[string]NamedParameter `yaml:"uriParameters"`

	// A RESTful API can be reached HTTP, HTTPS, or both
	Protocols []string `yaml:"protocols"`

	// The media types returned by API responses, and expected from API
	// requests that accept a body, MAY be defaulted by specifying the
	// mediaType property.
	// The property's value MAY be a single string with a valid media type:
	//
	// One of the following YAML media types:
	// * text/yaml
	// * text/x-yaml
	// * application/yaml
	// * application/x-yaml*
	//
	// Any type from the list of IANA MIME Media Types,
	// http://www.iana.org/assignments/media-types
	// A custom type that conforms to the regular expression:
	// * "application\/[A-Za-z.-0-1]*+?(json|xml)"
	MediaType string `yaml:"mediaType"`

	// The schemas property specifies collections of schemas that could be
	// used anywhere in the API definition.
	// The value of the schemas property is an array of maps; in each map,
	// the keys are the schema name, and the values are schema definitions:
	// []map[SchemaName]SchemaString
	Schemas []map[string]string

	// The securitySchemes property MUST be used to specify an API's security
	// mechanisms, including the required settings and the authentication
	// methods that the API supports.
	// []map[SchemeName]SecurityScheme
	SecuritySchemes []map[string]SecurityScheme `yaml:"securitySchemes"`

	// To apply a securityScheme definition to every method in an API, the
	// API MAY be defined using the securedBy attribute. This specifies that
	// all methods in the API are protected using that security scheme.
	// Custom parameters can be provided to the security scheme.
	SecuredBy []DefinitionChoice `yaml:"securedBy"`

	// The API definition can include a variety of documents that serve as a
	// user guides and reference documentation for the API. Such documents can
	// clarify how the API works or provide business context.
	// All the sections are in the order in which the documentation is declared.
	Documentation []Documentation `yaml:"documentation"`

	// To apply a trait definition to a method, so that the method inherits the
	// trait's characteristics, the method MUST be defined by using the is
	// attribute. The value of the is attribute MUST be an array of any number
	// of elements, each of which MUST be a) one or more trait keys (names)
	// included in the traits declaration, or b) one or more trait definition
	// maps.
	// []map[TraitName]Trait
	Traits []map[string]Trait `yaml:"traits"`

	// The resourceTypes and traits properties are declared at the API
	// definition's root level with the resourceTypes and traits property keys,
	// respectively. The value of each of these properties is an array of maps;
	// in each map, the keys are resourceType or trait names, and the values
	// are resourceType or trait definitions, respectively.
	// []map[ResourceTypeName]ResourceType
	ResourceTypes []map[string]ResourceType `yaml:"resourceTypes"`

	// Resources are identified by their relative URI, which MUST begin with a
	// slash (/). A resource defined as a root-level property is called a
	// top-level resource. Its property's key is the resource's URI relative
	// to the baseUri. A resource defined as a child property of another
	// resource is called a nested resource, and its property's key is its
	// URI relative to its parent resource's URI.
	Resources map[string]Resource `yaml:",regexp:/.*"`
}

The API Definition describes the basic information of an API, such as its title and base URI, and describes how to define common schema references.

func ParseFile 

func ParseFile(filePath string) (*APIDefinition, error)

Parse a RAML file. Returns a raml.APIDefinition value or an error if everything is something went wrong. This is the main entry point to the RAML parser.

func (*APIDefinition) GetResource 

func (r *APIDefinition) GetResource(path string) *Resource

This function receives a path, splits it and traverses the resource tree to find the appropriate resource

type Any 

type Any interface{}

"Any" type, for our convenience

type Bodies 

type Bodies struct {

	// As in the Body type.
	DefaultSchema string `yaml:"schema"`

	// As in the Body type.
	DefaultDescription string `yaml:"description"`

	// As in the Body type.
	DefaultExample string `yaml:"example"`

	// As in the Body type.
	DefaultFormParameters map[string]NamedParameter `yaml:"formParameters"`

	// Resources CAN have alternate representations. For example, an API
	// might support both JSON and XML representations. This is the map
	// between MIME-type and the body definition related to it.
	ForMIMEType map[string]Body `yaml:",regexp:.*"`
}

Container of Body types, necessary because of technical reasons.

type Body 

type Body struct {

	// The structure of a request or response body MAY be further specified
	// by the schema property under the appropriate media type.
	// The schema key CANNOT be specified if a body's media type is
	// application/x-www-form-urlencoded or multipart/form-data.
	// All parsers of RAML MUST be able to interpret JSON Schema [JSON_SCHEMA]
	// and XML Schema [XML_SCHEMA].
	// Alternatively, the value of the schema field MAY be the name of a schema
	// specified in the root-level schemas property
	Schema string `yaml:"schema"`

	// Brief description
	Description string `yaml:"description"`

	// Example attribute to generate example invocations
	Example string `yaml:"example"`

	// Web forms REQUIRE special encoding and custom declaration.
	// If the API's media type is either application/x-www-form-urlencoded or
	// multipart/form-data, the formParameters property MUST specify the
	// name-value pairs that the API is expecting.
	// The formParameters property is a map in which the key is the name of
	// the web form parameter, and the value is itself a map the specifies
	// the web form parameter's attributes
	FormParameters map[string]NamedParameter `yaml:"formParameters"`

	Headers map[HTTPHeader]Header `yaml:"headers"`
	// contains filtered or unexported fields
}

Some method verbs expect the resource to be sent as a request body. For example, to create a resource, the request must include the details of the resource to create. Resources CAN have alternate representations. For example, an API might support both JSON and XML representations.

type DefinitionChoice 

type DefinitionChoice struct {
	Name string

	// The definitions of resource types and traits MAY contain parameters,
	// whose values MUST be specified when applying the resource type or trait,
	// UNLESS the parameter corresponds to a reserved parameter name, in which
	// case its value is provided by the processing application.
	// Same goes for security schemes.
	Parameters DefinitionParameters
}

func (*DefinitionChoice) UnmarshalYAML 

func (dc *DefinitionChoice) UnmarshalYAML(unmarshaler func(interface{}) error) error

Unmarshal a node which MIGHT be a simple string or a map[string]DefinitionParameters

type DefinitionParameters 

type DefinitionParameters map[string]string

A ResourceType/Trait/SecurityScheme choice contains the name of a ResourceType/Trait/SecurityScheme as well as the parameters used to create an instance of it. Parameters MUST be of type string.

type Documentation 

type Documentation struct {
	Title   string `yaml:"title"`
	Content string `yaml:"content"`
}

All documentation of the API is of this format.

type HTTPCode 

type HTTPCode int // e.g. 200

For extra clarity

type HTTPHeader 

type HTTPHeader string // e.g. Content-Length

type Header NamedParameter

Headers used in Methods and other types

type Method 

type Method struct {
	Name string

	// Briefly describes what the method does to the resource
	Description string

	DisplayName string `yaml:"displayName"`

	// Applying a securityScheme definition to a method overrides whichever
	// securityScheme has been defined at the root level. To indicate that
	// the method is protected using a specific security scheme, the method
	// MUST be defined by using the securedBy attribute
	// Custom parameters can be provided to the security scheme.
	SecuredBy []DefinitionChoice `yaml:"securedBy"`

	// The method's non-standard HTTP headers. The headers property is a map
	// in which the key is the name of the header, and the value is itself a
	// map specifying the header attributes.
	Headers map[HTTPHeader]Header `yaml:"headers"`

	// A RESTful API method can be reached HTTP, HTTPS, or both.
	// A method can override an API's protocols value for that single method
	// by setting a different value for the fields.
	Protocols []string `yaml:"protocols"`

	// The queryParameters property is a map in which the key is the query
	// parameter's name, and the value is itself a map specifying the query
	//  parameter's attributes
	QueryParameters map[string]NamedParameter `yaml:"queryParameters"`

	// Some method verbs expect the resource to be sent as a request body.
	// A method's body is defined in the body property as a hashmap, in which
	// the key MUST be a valid media type.
	Bodies Bodies `yaml:"body"`

	// Resource methods MAY have one or more responses. Responses MAY be
	// described using the description property, and MAY include example
	// attributes or schema properties.
	// Responses MUST be a map of one or more HTTP status codes, where each
	// status code itself is a map that describes that status code.
	Responses map[HTTPCode]Response `yaml:"responses"`

	// Methods may specify one or more traits from which they inherit using the
	// is property
	Is []DefinitionChoice `yaml:"is"`
}

Methods are operations that are performed on a resource

type NamedParameter 

type NamedParameter struct {

	// The name of the Parameter, as defined by the type containing it.
	Name string

	// A friendly name used only for display or documentation purposes.
	// If displayName is not specified, it defaults to the property's key
	DisplayName string `yaml:"displayName"` // TODO: Auto-fill this

	// The intended use or meaning of the parameter
	Description string

	// The primitive type of the parameter's resolved value. Can be:
	//
	// Type	Description
	// string	- Value MUST be a string.
	// number	- Value MUST be a number. Indicate floating point numbers as defined by YAML.
	// integer	- Value MUST be an integer. Floating point numbers are not allowed. The integer type is a subset of the number type.
	// date		- Value MUST be a string representation of a date as defined in RFC2616 Section 3.3 [RFC2616]. See Date Representations.
	// boolean	- Value MUST be either the string "true" or "false" (without the quotes).
	// file		- (Applicable only to Form properties) Value is a file. Client generators SHOULD use this type to handle file uploads correctly.
	Type string

	// If the enum attribute is defined, API clients and servers MUST verify
	// that a parameter's value matches a value in the enum array
	Enum []Any `yaml:",flow"`

	// The pattern attribute is a regular expression that a parameter of type
	// string MUST match. Regular expressions MUST follow the regular
	// expression specification from ECMA 262/Perl 5. (string only)
	Pattern *string

	// The minLength attribute specifies the parameter value's minimum number
	// of characters (string only)
	MinLength *int `yaml:"minLength"`

	// The maxLength attribute specifies the parameter value's maximum number
	// of characters (string only)
	MaxLength *int `yaml:"maxLength"`

	// The minimum attribute specifies the parameter's minimum value. (numbers
	// only)
	Minimum *float64

	// The maximum attribute specifies the parameter's maximum value. (numbers
	// only)
	Maximum *float64

	// An example value for the property. This can be used, e.g., by
	// documentation generators to generate sample values for the property.
	Example string

	// The repeat attribute specifies that the parameter can be repeated,
	// i.e. the parameter can be used multiple times
	Repeat *bool // TODO: What does this mean?

	// Whether the parameter and its value MUST be present when a call is made.
	// In general, parameters are optional unless the required attribute is
	// included and its value set to 'true'.
	// For a URI parameter, its default value is 'true'.
	Required bool

	// The default value to use for the property if the property is omitted or
	// its value is not specified
	Default Any
	// contains filtered or unexported fields
}

The RAML Specification uses collections of named parameters for the following properties: URI parameters, query string parameters, form parameters, request bodies (depending on the media type), and request and response headers.

Some fields are pointers to distinguish Zero values and no values

type RamlError 

type RamlError struct {
	Errors []string
}

A RamlError is returned by the ParseFile function when RAML or YAML problems are encountered when parsing the RAML document.

func (*RamlError) Error 

func (e *RamlError) Error() string

type Resource 

type Resource struct {

	// Resources are identified by their relative URI, which MUST begin with
	// a slash (/).
	URI string

	// A resource defined as a child property of another resource is called a
	// nested resource, and its property's key is its URI relative to its
	// parent resource's URI. If this is not nil, then this resource is a
	// child resource.
	Parent *Resource

	// A friendly name to the resource
	DisplayName string

	// Briefly describes the resource
	Description string

	// A securityScheme may also be applied to a resource by using the
	// securedBy key, which is equivalent to applying the securityScheme to
	// all methods of this Resource.
	// Custom parameters can be provided to the security scheme.
	SecuredBy []DefinitionChoice `yaml:"securedBy"`

	// A resource or a method can override a base URI template's values.
	// This is useful to restrict or change the default or parameter selection
	// in the base URI. The baseUriParameters property MAY be used to override
	// any or all parameters defined at the root level baseUriParameters
	// property, as well as base URI parameters not specified at the root level.
	// In a resource structure of resources and nested resources with their
	// methods, the most specific baseUriParameter fully overrides any
	// baseUriParameter definition made before
	BaseUriParameters map[string]NamedParameter `yaml:"baseUriParameters"`

	// Template URIs containing URI parameters can be used to define a
	// resource's relative URI when it contains variable elements.
	// The values matched by URI parameters cannot contain slash (/) characters
	UriParameters map[string]NamedParameter `yaml:"uriParameters"`

	// Resources may specify the resource type from which they inherit using
	// the type property. The resource type may be defined inline as the value
	// of the type property (directly or via an !include), or the value of
	// the type property may be the name of a resource type defined within
	// the root-level resourceTypes property.
	// NOTE: inline not currently supported.
	Type *DefinitionChoice `yaml:"type"`

	// A resource may use the is property to apply the list of traits to all
	// its methods.
	Is []DefinitionChoice `yaml:"is"`

	// In a RESTful API, methods are operations that are performed on a
	// resource. A method MUST be one of the HTTP methods defined in the
	// HTTP version 1.1 specification [RFC2616] and its extension,
	// RFC5789 [RFC5789].
	Get    *Method `yaml:"get"`
	Head   *Method `yaml:"head"`
	Post   *Method `yaml:"post"`
	Put    *Method `yaml:"put"`
	Delete *Method `yaml:"delete"`
	Patch  *Method `yaml:"patch"`

	// A resource defined as a child property of another resource is called a
	// nested resource, and its property's key is its URI relative to its
	// parent resource's URI.
	Nested map[string]*Resource `yaml:",regexp:/.*"`
}

A resource is the conceptual mapping to an entity or set of entities.

func (*Resource) Methods 

func (r *Resource) Methods() []*Method

type ResourceType 

type ResourceType struct {

	// Name of the resource type
	Name string

	// The usage property of a resource type or trait is used to describe how
	// the resource type or trait should be used
	Usage string

	// Briefly describes what the resource type
	Description string

	// As in Resource.
	UriParameters map[string]NamedParameter `yaml:"uriParameters"`

	// As in Resource.
	BaseUriParameters map[string]NamedParameter `yaml:"baseUriParameters"`

	// In a RESTful API, methods are operations that are performed on a
	// resource. A method MUST be one of the HTTP methods defined in the
	// HTTP version 1.1 specification [RFC2616] and its extension,
	// RFC5789 [RFC5789].
	Get    *ResourceTypeMethod `yaml:"get"`
	Head   *ResourceTypeMethod `yaml:"head"`
	Post   *ResourceTypeMethod `yaml:"post"`
	Put    *ResourceTypeMethod `yaml:"put"`
	Delete *ResourceTypeMethod `yaml:"delete"`
	Patch  *ResourceTypeMethod `yaml:"patch"`

	// When defining resource types and traits, it can be useful to capture
	// patterns that manifest several levels below the inheriting resource or
	// method, without requiring the creation of the intermediate levels.
	// For example, a resource type definition may describe a body parameter
	// that will be used if the API defines a post method for that resource,
	// but the processing application should not create the post method itself.
	//
	// This optional structure key indicates that the value of the property
	// should be applied if the property name itself (without the question
	// mark) is already defined (whether explicitly or implicitly) at the
	// corresponding level in that resource or method.
	OptionalUriParameters     map[string]NamedParameter `yaml:"uriParameters?"`
	OptionalBaseUriParameters map[string]NamedParameter `yaml:"baseUriParameters?"`
	OptionalGet               *ResourceTypeMethod       `yaml:"get?"`
	OptionalHead              *ResourceTypeMethod       `yaml:"head?"`
	OptionalPost              *ResourceTypeMethod       `yaml:"post?"`
	OptionalPut               *ResourceTypeMethod       `yaml:"put?"`
	OptionalDelete            *ResourceTypeMethod       `yaml:"delete?"`
	OptionalPatch             *ResourceTypeMethod       `yaml:"patch?"`
}

Resource and method declarations are frequently repetitive. For example, if an API requires OAuth authentication, the API definition must include the access_token query string parameter (which is defined by the queryParameters property) in all the API's resource method declarations.

Moreover, there are many advantages to reusing patterns across multiple resources and methods. For example, after defining a collection-type resource's characteristics, that definition can be applied to multiple resources. This use of patterns encouraging consistency and reduces complexity for both servers and clients.

A resource type is a partial resource definition that, like a resource, can specify a description and methods and their properties. Resources that use a resource type inherit its properties, such as its methods.

type ResourceTypeMethod 

type ResourceTypeMethod struct {
	Name string

	// Briefly describes what the method does to the resource
	Description string

	// As in Method.
	Bodies Bodies `yaml:"body"`

	// As in Method.
	Headers map[HTTPHeader]Header `yaml:"headers"`

	// As in Method.
	Responses map[HTTPCode]Response `yaml:"responses"`

	// As in Method.
	QueryParameters map[string]NamedParameter `yaml:"queryParameters"`

	// As in Method.
	Protocols []string `yaml:"protocols"`
}

Method that is part of a ResourceType. DIfferentiated from Traits since it doesn't contain Usage, optional fields etc.

type Response 

type Response struct {

	// HTTP status code of the response
	HTTPCode HTTPCode

	// Clarifies why the response was emitted. Response descriptions are
	// particularly useful for describing error conditions.
	Description string

	// An API's methods may support custom header values in responses
	Headers map[HTTPHeader]Header `yaml:"headers"`

	// Each response MAY contain a body property. Responses that can return
	// more than one response code MAY therefore have multiple bodies defined.
	Bodies Bodies `yaml:"body"`
}

Resource methods MAY have one or more responses.

type SecurityScheme 

type SecurityScheme struct {
	Name string

	// Briefly describes the security scheme
	Description string

	// The type attribute MAY be used to convey information about
	// authentication flows and mechanisms to processing applications
	// such as Documentation Generators and Client generators.
	Type string

	// The describedBy attribute MAY be used to apply a trait-like structure
	// to a security scheme mechanism so as to extend the mechanism, such as
	// specifying response codes, HTTP headers or custom documentation.
	// This extension allows API designers to describe security schemes.
	// As a best practice, even for standard security schemes, API designers
	// SHOULD describe the security schemes' required artifacts, such as
	// headers, URI parameters, and so on.
	// Including the security schemes' description completes an API's documentation.
	DescribedBy SecuritySchemeMethod

	// The settings attribute MAY be used to provide security schema-specific
	// information. Depending on the value of the type parameter, its attributes
	// can vary.
	Settings map[string]Any

	// If the scheme's type is x-other, API designers can use the properties
	// in this mapping to provide extra information to clients that understand
	// the x-other type.
	Other map[string]string
}

Most REST APIs have one or more mechanisms to secure data access, identify requests, and determine access level and data visibility.

type SecuritySchemeMethod 

type SecuritySchemeMethod struct {
	Bodies          Bodies                    `yaml:"body"`
	Headers         map[HTTPHeader]Header     `yaml:"headers"`
	Responses       map[HTTPCode]Response     `yaml:"responses"`
	QueryParameters map[string]NamedParameter `yaml:"queryParameters"`
}

A trait-like structure to a security scheme mechanism so as to extend the mechanism, such as specifying response codes, HTTP headers or custom documentation.

type Trait 

type Trait struct {
	Name string

	// The usage property of a resource type or trait is used to describe how
	// the resource type or trait should be used
	Usage string

	// Briefly describes what the method does to the resource
	Description string

	// As in Method.
	Bodies Bodies `yaml:"body"`

	// As in Method.
	Headers map[HTTPHeader]Header `yaml:"headers"`

	// As in Method.
	Responses map[HTTPCode]Response `yaml:"responses"`

	// As in Method.
	QueryParameters map[string]NamedParameter `yaml:"queryParameters"`

	// As in Method.
	Protocols []string `yaml:"protocols"`

	// When defining resource types and traits, it can be useful to capture
	// patterns that manifest several levels below the inheriting resource or
	// method, without requiring the creation of the intermediate levels.
	// For example, a resource type definition may describe a body parameter
	// that will be used if the API defines a post method for that resource,
	// but the processing application should not create the post method itself.
	//
	// This optional structure key indicates that the value of the property
	// should be applied if the property name itself (without the question
	// mark) is already defined (whether explicitly or implicitly) at the
	// corresponding level in that resource or method.
	OptionalBodies          Bodies                    `yaml:"body?"`
	OptionalHeaders         map[HTTPHeader]Header     `yaml:"headers?"`
	OptionalResponses       map[HTTPCode]Response     `yaml:"responses?"`
	OptionalQueryParameters map[string]NamedParameter `yaml:"queryParameters?"`
}

A trait is a partial method definition that, like a method, can provide method-level properties such as description, headers, query string parameters, and responses. Methods that use one or more traits inherit those traits' properties.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.