apispec

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