lib-apidoc
Create JavaScript apidoc clients
Code generator for apidoc that will take in an object representing an apidoc service and return a list of objects representing files for the client.
The generated code is isomorphic, depending on a native fetch
implementation
in the browser and node-fetch
in a node.js environment.
Requirements
-
apidoc - This library depends on data from apidoc - http://www.apidoc.me. An api hosted here generates a
service.json
file - the JSON representation of the service. - node-fetch - In a node.js environment the generated code depends on - https://www.npmjs.com/package/node-fetch
Installation
npm install --save-dev @flowio/lib-apidoc
Usage
A basic example of generating a JavaScipt client from an apidoc service.
import fs from 'fs';
import path from 'path';
import service from './service.json';
import { codegen } from '@flowio/lib-apidoc';
const clientBasePath = path.join(__dirname, './dist');
const client = codegen.generate(service);
client.files.forEach((file) => {
fs.writeFileSync(path.join(clientBasePath, file.path), file.contents);
});
API Reference
codegen
Methods
The methods listed below can be accessed from codegen
.
generate(service: Object, options: Object): Array
The argument passed to the generate
function is:
-
service
- JSON representation of a service. Theservice.json
provided by apidoc -
options
-
clientImportPath
- path to where generated client.js file will be located relative to service resource js files. Default is.
(the current directory).
-
Returns an array of file objects that have this shape:
{
contents: "import Client from './client'\nexport default class Resource...",
path: 'resource.js'
}
Generated Code
By default lib-apidoc will take in a service json object and return a list of objects representing files.
Directory Layout
If you write all of the files based on their path
property you will end up with a directory structure that looks like the below.
Path | Description |
---|---|
./client.js |
Class that handles bootstrapping a client and http (via fetch ) request / response handling |
./index.js |
The entrypoint to the client |
./logger.js |
Logging utility |
./resource_1.js |
A service resource that would be located at (in service.json): .resources[plural=resource_1]
|
./resource_2.js |
A service resource that would be located at (in service.json): .resources[plural=resource_2]
|
./resource_3.js |
A service resource that would be located at (in service.json): .resources[plural=resource_3]
|
Client Usage
Example creating a module that exposes a function to create an instance of a client with a default value for the api host.
import Client from './client';
export default function CreateClient(opts) {
let options = {
host: 'https://api.example.com',
};
if (typeof opts === 'string') {
options.auth = opts;
} else {
options = Object.assign({}, options, opts);
}
return new Client(options);
}
Options
Name | Type | Description |
---|---|---|
host | String | The http host / uri of the api |
auth | String | Converted to a Basic Authorization |
auth | Object | Basic or Bearer authorization |
-- auth.type | String | One of: basic , bearer , jwt . bearer and jwt are synonymous with each other |
-- auth.value | String | The value of the Authorization header |
headers | Object | Headers to be passed with all http requests from the client |
serviceName | String | The name of the service (currently unused) |
Resource Usage
import Client from './client'
const client = new Client({ host: 'https://api.example.com' })
// Example of using the 'get' operation on the 'users' resource.
client.users.get().then((response) => {
switch(response.status) {
case 200:
response.result.map((user) =>
console.log(`Found User: ${user.email}`))
case 401:
throw new Error('Was not authorized to get users!')
default:
throw new Error(`Response code[${response.status}] not handled!`)
}
})
Options
All options mentioned above in the client usage and any fetch
options can be
provided as the only or last parameter to a resource operation.
Contributing / Issues / Questions
If you would like to contribute to lib-apidoc, have any bugs to report or have general questions, please see our contributing guidelines.