Skip to content

Latest commit

 

History

History
96 lines (64 loc) · 2.44 KB

DEVELOPER.md

File metadata and controls

96 lines (64 loc) · 2.44 KB

Overview

Designed to host API documentation for REST services. See spec/api.json for description of the API. Code generators for various languages & frameworks are independent of this application. Official generators can be found in apidoc-generators.

Projects

There are several projects within the apidoc repo.

core

Contains shared code to parse an api.json file into case classes, including validation on the document in a way that is friendly to users.

api

apidoc REST service itself. See spec/api.json contains the description of the API.

www

Actual UI for apidoc.

Generated Code

The .apidoc file lists the specific targets which are generated by apidoc. To regenerate code, clone github.com/mbryzek/apidoc-cli and

bin/apidoc update

In development:

APIDOC_API_URI="http://localhost:9001" /web/apidoc-cli/bin/apidoc update

Updating apidoc.me

/web/apidoc-cli/bin/apidoc upload gilt apidoc-spec ./spec/service.json --version 0.9.3 /web/apidoc-cli/bin/apidoc upload gilt apidoc-generator ./spec/generator.json --version 0.9.3 /web/apidoc-cli/bin/apidoc upload gilt apidoc-api ./spec/api.json --version 0.9.3

SBT

Memory settings for SBT:

exec java -Xms512M -Xmx2048M -XX:MaxPermSize=1G -Xss1M -XX:+CMSClassUnloadingEnabled \ 
  ${SBT_OPTS} -jar /usr/local/Cellar/sbt/0.13.5/libexec/sbt-launch.jar "$@"

Developing

You'll need to get the api schema into your dev postgresql database; to do that:

$ psql
psql> CREATE DATABASE api;

Then you'll need to create the database schema using schema evolution manager

$ cd /web/apidoc/schema
$ ./dev.rb

The application consists of a service on port 9001, and a web app on port 9000.

One way to do this is to run a screen session, and in one screen do:

$ sbt
sbt> project api
sbt> run 9001

...then in another screen, do:

$ sbt
sbt> project www
sbt> run

Goto http://localhost:9000 in your browser

If you want to run the standard code generators:

$ sbt
sbt> project generator
sbt> run 9002

Goto http://localhost:9002/generators in your browser

Now both should be running and able to talk to each other, and should recompile in situ for a nice development experience.

Updating generated code

/web/apidoc-cli/bin/apidoc update