Generate API clients by documenting your api implementation
MIT License
This project is in development phase. Please follow/star the project to receive notifications when a release is available.
Generate api clients by documenting you api implementation. apigen
is
a simple DSL for documenting your API. After documenting, apigen
can
understand the DSL and generate clients for your API (so you don't have
to). There are several apigen
generators for mayor languages/frameworks.
Is as simple as this:
# Finds a user given the user's id
# returns :404 if the user is not found
# get /users/{user_id}/show
# @path {int} user_id the user's id
def find_user_by_id
user = User.find(params[:id])
if user
respond_with :200, user
else
respond_with :404, "User not found"
end
end
To specify the method and url use the following syntax {method_name} {url}
. The following methods
are supported: get, post, put, delete (head, options, patch to come)
Example: A simple get request
# get /users
def index
User.all
end
Path parameters can be specified using sinatra/rails syntax {param_name}
.
Example:
# delete /users/{user_id}
def delete_by_id
# method implementation
end
Example: specifying several params
# get /users/{user_id}/friends/{friend_id}
def find_friend
# method implementation
end
Query parameters can be specified using the following syntax @query {type} name description
where
type
is one of string
, int
, boolean
or float
. The type isstring
is the default type.name
is the name of the parameter, any alphanumeric string startinglowercase_underscored
names)description
is a string that describes the attribute.Example:
# get /users
# @query {string} name The user's name
def find_users_by_name
Headers can be specified per method using the following syntax @header name value
Example:
# get /users
# @header Content-Type application/json
def users
The Config file specifies all the configuration needed to load Apigen with the generators you wish to use.
The structure of the file is as follows
Example: This config file example takes one input file and applies two generators, apigen-ruby and apigen-python.
You can specify any number of generators. The opts parameter is optional, it is passed on to the generator, different genrators may require that you pass different options.
"input": "~/apps/my_rails_app/app/controllers/users_controller.rb",
"generators": [
{
"require": "apigen-ruby",
"out": "~/apps/gems/apigen_ruby/lib/users_api.rb",
"opts" : {
"name": "UsersApi"
}
},
{
"require": "apigen-python"
"out": "~/apps/pips/apigen_py/users_api.py",
"opts" : {}
}
]
This is a list of all known generators.
apigen-json
: https://github.com/fhur/apigen-json
apigen-markdown
: https://github.com/fhur/apigen-markdown