omapi

Implementation of the OpenMergeAPI specs, omapi (said "Oh Map-ee!") is a command line and Node.js utility for building and merging OpenAPI endpoints and schemas.

Introduction

Let's discover omapi in less than 5 minutes.

You'll need Node.js version 20.0 or above.

Initialize the Project

Create a new directory and initialize npm:

mkdir my-api
cd my-api
npm init -y

Install dependencies:

npm install --save-dev omapi @omapi/generator-routes

• omapi - The core CLI (this library).
• @omapi/generator-routes - This plugin generates output for common routers.

Create your API

Add an API endpoint for GET /hello by adding the file api/paths/hello/[email protected] with this:

export const summary = 'Says Hello'
export const description = 'Simple example using the NodeJS http request/response model.'
export default async (request, response) => {
	response.statusCode = 200
	response.setHeader('Content-Type', 'text/plain')
	response.end('Hello World!')
}

Configure

Add a configuration file omapi.config.js with this:

import routes from '@omapi/generator-routes'
export default {
	input: './api',
	output: './build',
	generators: [
		routes(),
	],
}

And to your package.json file, add a run script for building:

{
	"scripts": {
		"build": "omapi -c"
	}
}

Now build by running the following command in your terminal:

npm run build

Run the Server

OpenMergeAPI does not have opinions about how you handle requests, and neither does omapi, but in this demo we're using a simple implementation of Node.js createServer.

Add a file server.js and put in it:

import { createServer } from 'node:http'
import { routes } from './build/routes.js'

const server = createServer((request, response) => {
	// a very rudimentary router, as omapi does not include a default
	for (const { path, method, handler } of routes) {
		if (request.url === path && request.method.toLowerCase() === method) {
			return handler(request, response)
		}
	}
})

server.listen(3000, '127.0.0.1', () => {
	console.log('Server running!')
})

Then start the server by running this command from your terminal:

node ./server.js

Now make a request to 127.0.0.1:3000/hello to see the server response:

> curl http://127.0.0.1:3000/hello
Hello World!

License

This software and all example code are dedicated to the public domain.