Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/lucid-services/serviser-doc
automated API documentation for `serviser` based apps
https://github.com/lucid-services/serviser-doc
automation documentation open-api serviser swagger swagger-ui
Last synced: 23 days ago
JSON representation
automated API documentation for `serviser` based apps
- Host: GitHub
- URL: https://github.com/lucid-services/serviser-doc
- Owner: lucid-services
- License: gpl-3.0
- Created: 2019-02-07T09:02:07.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2023-01-07T03:31:05.000Z (almost 2 years ago)
- Last Synced: 2024-09-30T15:13:08.019Z (about 1 month ago)
- Topics: automation, documentation, open-api, serviser, swagger, swagger-ui
- Language: JavaScript
- Homepage:
- Size: 4.51 MB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 30
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://travis-ci.org/lucid-services/serviser-doc)
This `serviser` plugin generates documentation (`swagger-ui` like frontend) for `serviser` Apps.
Here is how it works in few steps:
* During service initialization, available `App`s are fetched from `AppManager`
* Open API (OAS) REST API specification is generated from static route definitions
* For each `App` in `AppManager`, corresponding (additional) `Doc` http app (which serves the documentation frontend) is created and pushed into internal `AppManager` stack
* As `Doc` http apps implement the same interface of generic http `App` object, the service initialization process continues as it would without any documentation being generated.
### USAGE
* Hook up the plugin into your application in your app's `index.js` file:
```javascript
const config = require('serviser-config');
const Service = require('serviser');
//service initialization stuff...
const service = new Service(config);
//...
//hook-up the plugin
require('serviser-doc');
```
* Enable automatic Doc app generation in your service `config.json5`:
```javascript
{
apps: {
appName: {
// provide the doc configuration section for each app you want
// the documentation to be generated for
doc: {
baseUrl: 'http://127.0.0.1:3000',
listen: 3000,
title: 'User API', //optional
stopOnError: true, //optional
//allows us to include hand-crafted API description for each version
readme: { //optional
'v2.0': 'lib/routes/v2.0/README.md'
}
}
}
}
}
```
### From what the docs are generated?
- [Router](https://lucid-services.github.io/serviser/Router.html) & [Route](https://lucid-services.github.io/serviser/Route.html) definitions - more specifically `desc` & `summary` constructor options.
- Validation schema definitions provided to the [route.validate](https://lucid-services.github.io/serviser/Route.html#validate) & [route.respondsWith](https://lucid-services.github.io/serviser/Route.html#respondsWith) methods.
- Supported request `content-type(s)` as defined via [route.acceptsContentType](https://lucid-services.github.io/serviser/Route.html#acceptsContentType)
- Custom `Ajv` keyword `$desc` which `serviser` provides, can be used to describe individual request/response data properties in user defined `Route` validation schemas.
```javascript
route.respondsWith({ //200 - OK response
type: 'object',
properties: {
is_active: {
type: 'boolean',
$desc: 'Whether the user has been online within a period of last 7 days'
}
}
});
//
route.validate({
username: {type: 'string'}
}, 'params');
```
- Possible route error responses can be described also by the `route.respondsWith` method:
```javascript
route.respondsWith(RequestError);
route.respondsWith(new RequestError({
apiCode: 'tag.alreadyExists'
message: 'Tag already exists'
}));
route.respondsWith(UnauthorizedError);
```
Also see `serviser` [Error management](https://lucid-services.github.io/serviser/tutorial-1b.ErrorManagement.html)