Libraries for generating code and documenation for apidoc projects
npm install @flowio/lib-apidoc> Create JavaScript apidoc clients
!Travis Build
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.
- 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
``bash`
npm install --save-dev @flowio/lib-apidoc
A basic example of generating a JavaScipt client from an apidoc service.
`JavaScript
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);
});
`
#### 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. The service.json provided by apidocoptions
-
- - 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:
`JavaScript`
{
contents: "import Client from './client'\nexport default class Resource...",
path: 'resource.js'
}
By default lib-apidoc will take in a service json object and return a list of
objects representing files.
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]
| | A service resource that would be located at (in service.json): .resources[plural=resource_2]
| | A service resource that would be located at (in service.json): .resources[plural=resource_3]
Example creating a module that exposes a function to create an instance of a
client with a default value for the api host.
`JavaScript
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)
`JavaScript
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}))Response code[${response.status}] not handled!
case 401:
throw new Error('Was not authorized to get users!')
default:
throw new Error()`
}
})
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.
If you would like to contribute to lib-apidoc, have any bugs to report or have general questions, please see our contributing guidelines.