go-raml

by Jumpscale

Jumpscale / go-raml

RAML 1.0 implementation

124 Stars 34 Forks Last release: over 4 years ago (v0.1) BSD 2-Clause "Simplified" License 915 Commits 2 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

go-raml

Build Status

Table of Contents

planning

What is go-raml

When creating and maintaining api's, there are two approaches: * Design first

You design the api, all methods, descriptions and types from the api point of view. Afterwards, you generate all the boilerplate code and documentation to bootstrap the code.
  • Code first

    When modifying the implementation, the interface definitions need to be kept in sync. Besides the good practice of keeping your specification up to date, it is used by other tools to generate clients, documentation, ...

This tool supports both (or at least, this is on the roadmap). As a specification format, it uses RAML 1.0 .

It currently has these features:

  • generate server stub in Go, Python, and Nim from an raml file.
  • generate complete client library in Go, Python, and Nim from an RAML file.
  • generate capnp schema. See capnp docs for details.

RAML versions

Only RAML version 1.0 RC is supported.

Currently there are still some limitations on the RAML 1.0 features that are supported.

Install

make sure you have at least go 1.8 installed !

go get -u github.com/Jumpscale/go-raml

Build in development

Install

dep
as package manager, we need it for vendoring tool

`$go get -u github.com/golang/dep/cmd/dep

Install go-bindata, we need it to compile all resource files to .go file

go get -u github.com/jteeuwen/go-bindata/...

To rebuild APIDocs files to .go file

cd $GOPATH/src/github.com/Jumpscale/go-raml
sh build_apidocs.sh

Build go-raml and all resource files

cd $GOPATH/src/github.com/Jumpscale/go-raml
make install

Code generation

Internally, go templates are used to generate the code, this provides a flexible way to alter the generated code and to add different languages for the client.

Usage

To use it on the commandline, just execute

go-raml
without any arguments, it will output the help on the stdout.

To invoke the codegeneration using

go generate
, specify the generation in 1 of your go source files:
//go:generate go-raml ...

go-raml needs to be on the path for this to work off course.

Generating Server

go-raml
able to generate Go & Python server. Nim server is under development.

Generated server will listen on port 5000

Go Server

To generate the Go code for implementing the server in first design approach, execute

go-raml server -l go --dir /gopath/src/github.com/mycompany/myapi --ramlfile api.raml --import-path github.com/mycompany/myapi

--dir
specify generated code directory. Except you really know what you do, use $GOPATH as root directory. In above example $GOPATH is /gopath.

--ramlfile
is the path RAML file

--import-path
is the root import path of the code. Generated code contains sub packages and need it to properly import code from another packages

Python Server

Executes this command to generates Flask server

go-raml server -l python --dir ./result_directory --ramlfile api.raml

Executes this command to generates Sanic server

go-raml server -l python --dir ./result_directory --ramlfile api.raml --kind sanic

Code Generator Options

   ----language, -l "go"                        Language to construct a server for
   --kind                                       Kind of server to generate (, sanic) (only for python)
   --dir "."                                    target directory
   --ramlfile "."                               Source raml file
   --package "main"                             package name
   --no-main                                    Do not generate a main.go file
   --no-apidocs                                 Do not generate API Docs in /apidocs/ endpoint
   --import-path "examples.com/ramlcode"        import path of the generated code
   --lib-root-urls                              Array of libraries root URLs 

Generating Client

go-raml client --language go  --dir ./result_directory --ramlfile api.raml

A go 1.5.x compatible client is generated in result_directory directory.

go-raml client --language python --dir ./result_directory --ramlfile api.raml
or

go-raml client --language python --dir ./result_directory --ramlfile api.raml --kind aiohttp

A python 3.5 compatible client is generated in result_directory directory.

Code Generator Options

OPTIONS:
   --language, -l "go"      Language to construct a client for
   --dir "."            target directory
   --ramlfile "."       Source raml file
   --package "client"       package name
   --import-path        golang import path of the generated code
   --kind "requests"        Kind of python client to generate (requests,aiohttp)
   --lib-root-urls      Array of libraries root URLs
   --python-unmarshall-response set to true for python client to unmarshall the response into python class

Generating Docs

go-raml docs [--format markdown] --ramlfile api.raml --output api.md

A single file

markdown
documentation is generated. Note that only markdown format is supported at the moment.

Using Generated Code

Simple home page and API Docs

Both servers have simple HTML home page that can be accessed in http://localhost:5000. it provide simple description of the API server and link to auto generated API Documentation powered by api-console

Using Go Server

Generated go server can be used as your API server skeleton. It gives you routing code, implementation skeleton, simple request validation, and all struct based on raml types and request/response body. You can then extend the generated code to fit your need.

Generated code details:

  • an optional main file which contain routing code and other inialization code
  • Interfaces files, contain routing code which mapped one to one with RAML resources. It always regenerated
  • Interface implementation. It is code skeleton of the resource implemetation, only generated when the file is not present. So you can easily modify it
  • Struct for RAML types and request/response body, only generated when the file is not present.
  • Validation code
  • Helper files

The generated server uses Gorilla Mux as HTTP request multiplexer.

install required packages

 $go get github.com/gorilla/mux
 $go get gopkg.in/validator.v2
 $go get github.com/justinas/alice

Build the code

go build ./...

Execute it

./binary_name

The server will then run in port 5000, you can go to http://localhost:5000 to see default html page as described above

Using Python Server

The generated code is utilizing Flask Blueprint to give you modular flask code. The Sanic version also use Sanic Blueprint.

Generated code details:

  • main file named app.py which initialize the app
  • one bluperint/module for each root RAML resource
  • helper file
  • requirements.txt which contains list of packages needed to run the app.
  • all files are overwritten when the server is regenerated even if they exist except for the handlers files under handlers/

Install needed packages

pip3 install -r requirements.txt

You might want to install it inside virtualenv

Run the code

python3 app.py

The server will then run in port 5000, you can go to http://localhost:5000 to see default html page as described above

Using Go client library

Generated go client library can be used directly as modular package of your project.

It has

AuthHeader
field, which if not empty will be used as value of
Authorization
header on each request.

Using Python Client library

We provide two kind of clients:

  • sync client using popular
    requests
    http library
  • async client using
    aiohttp
    library, this client will give more performance

It has

set_auth_header
method to set
Authorization
header value on each request. All files are overwritten when the client is regenerated.

Specification file

Besides generation of a new RAML specification file, updating an existing raml file is also supported. This way the raml filestructure that can be included in the main raml file is honored.

go-raml spec ...

Viewing and Editing RAML File

There are many ways to view and edit RAML file:

  • API Workbench is an atom package for designing, building, testing, documenting and sharing RESTful HTTP APIs
  • Vim : it is enough for simple purpose

Contribute

When you want to contribute to the development, follow the contribution guidelines.

Roadmap

v0.1

  • Generation of the server using gorilla mux
  • Generation of a go client
  • Generation of a python 3.5 client
  • Generation of a python flask server

v0.2

  • OAuth 2.0 support
  • Input validation according to the RAML type definitions

v0.3

  • Possibility to generate a default server implementation to MongoDB

v0.4

  • Generation of a new RAML specification file

v0.5

  • Update of a RAML specification file

RAML to Code Translation

Short descriptions about how the generator generates the code from raml file are available in these docs:

Tutorial

Tutorial for Go, Python, and Nim is available at docs/tutorial directory

Check all the available go commands here

Check all the available python commands here

Check all the available nim commands here

CREDITS

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.