#ApiSpec Reader for Node.js/Express stack. ##Warning: This is purely experimental and should not be used in a production environment The apispec file format allows for creating complex apis with modules to handle routes.

name: Example API #Name the api
version: "1.0_rc2" #Api version. Not currently used but may implement a version scheme if you desire.
language: JavaScript #You must set a language for the server. This allows for spec files to be used in different languages, such as java or php.
module-aliases: #Case-sensitive!
    Authenticate: /example/auth.js #Add the user-defined authenticate module
    #You can override pre-defined modules here.
#There are a few pre-defined modules,
#Text, which uses the text option to send text
#PSQL, which querys the psql server defined in process.env.DATABASE_URL. Define input variables and their keys using an array called values
#File, which sends a file with the specified name, from the public/ folder

modules:
#    - ForceSSL
#    - Authenticate
paths:
    /:
        text: Hello and Welcome to my site! <a href="/file">Test</a> #Static text
    /file: 
        module: File #Send a file
        file: /example/public/test.html #File to send from public folder
    /favicon.ico:
        module: File
        file: /example/public/icon.png
    /api/core:
        paths:
            /search:
                method: GET #This is optional for get paths
                text: Hello World! #Send Hello, World Text
    /api/user:
        modules: 
            - Authenticate #Only Let Registered Users pass through to sub-paths of /api/user
        read: 
            authid: Int #Store user id
            authtoken: String #Store auth token
        paths:
            /me: 
                module: PSQL #Load the sql route module
                sql: SELECT * from users WHERE true #List all users
                single: false #This is not a single query
            /example:
                module: PSQL
                sql: SELECT * from users WHERE id = $1 LIMIT 1
                values: 
                    - authid #bind $1 to authid. 
                    ##List other parameters in order
                single: true #Expect exactly result.
            /secure: 
                paths:
                    /text: 
                        text: Hello!           
    /test:
        text: Hello World!
    /vm:
        module: VM
        javascript: |
                //Handle is the publicly exposed function
                function handle(req, res, next){
                    res.status(200).send("Hello From a VM! " + Date.now());
                }

#Invoking in express

var parser = require('apispec')(app, express, 'spec.yaml', __dirname);

//__dirname is passed to the spec parser so all modules can use the proper directory

#Running example

npm run example

#Core modules ###File Allows you to serve a file on an endpoint

/file: 
    module: File #Send a file
    file: test.html #File to send from public/ folder

###Text Allows you to serve static text on an endpoint

/text: 
    text: Hello!

###PSQL Allows you to query a database and serve the query results note: You should install and add the 'pg' module to your package.json to use the PSQL route

/database-search:
    module: PSQL #Select PSQL module
    sql: SELECT * from users WHERE id = $1 LIMIT 1 #Define the query
    values: 
        - authid #bind $1 to authid. 
        ##List other parameters in order
    single: true #Expect exactly one result

###ForceSSL forces all children endpoints to use ssl. You can use this in the top-level modules list

/secure: 
    route: true
    module: ForceSSL
    paths:
        #List child paths here

###VM Allows for handlers to be written directly inside the specfile (recommended for only small handlers)

/vm:
    module: VM
    javascript: |
            //Handle is the publicly exposed function
            function handle(req, res, next){
                res.status(200).send("Hello From a VM! " + Date.now());
            }

This code is released under the MIT licence