Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/christoph-jerolimov/bo-swag
A lightweight solution to create swagger documentation with ExpressJS
https://github.com/christoph-jerolimov/bo-swag
Last synced: about 1 month ago
JSON representation
A lightweight solution to create swagger documentation with ExpressJS
- Host: GitHub
- URL: https://github.com/christoph-jerolimov/bo-swag
- Owner: christoph-jerolimov
- Created: 2014-11-05T16:56:50.000Z (about 10 years ago)
- Default Branch: master
- Last Pushed: 2014-11-19T20:45:45.000Z (about 10 years ago)
- Last Synced: 2024-11-04T19:52:53.459Z (about 2 months ago)
- Language: JavaScript
- Homepage:
- Size: 240 KB
- Stars: 1
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# bo-swag [![Build status][travis-image]][travis-url] [![Test coverage][coveralls-image]][coveralls-url] [![Dependency Status][dependency-image]][dependency-url]
## A lightweight solution to create swagger documentation with ExpressJS
Status: **Work in progress**
## Installation
npm install bo-swag --save
## DRY.
Just wrap your ExpressJS app or router. All origin functions are still available!!
```js
var express = require('express'),
swag = require('bo-swag'),
app = swag.wrap(express());
```
Standard call of .get, .use. or other verbs works as expected and generate NO API doc for you:
```js
app.get('/', function (req, res) {
res.send('Hello World!')
})
```
But if you provide a small documentation hint this project will automatically generate an API doc for you:
```js
// Name => Standard JSON-scheme
app.addDefinition('Car', {
title: 'Cars',
type: Object,
properties: {
manufacturer: { type: String },
model: { type: String }
}
});
app.get('/cars', { response: 'Cars' }, function (req, res) {
// ...
})
app.post('/cars', { body: 'Car' }, function (req, res) {
// ...
})
```
This exmaple show how you can use multiple attributs. Expect
some shortcuts like `body` you can use all swagger documentation
attributes here!
Shortcuts? Yes! `body: 'A String'` is a shortcut and will be
automatically expanded to `parameters: [ { in: 'body', name: 'body', schema: { $ref: '#/definitions/A String' } } ]`.
```js
app.post('/api', {
summary: 'Just an example',
body: 'Example'
}, function (req, res) {
res.send('Hello World!')
})
```
If you want load your definitions from an external spec
javascript or json file, you can merge your input easily:
```js
app.spec.load(require('./spec.js'));
```
To include the swagger-ui (static HTML and a dynamically
generated swagger.json) just include the middleware.
```js
app.use('/explorer', swag.middleware(spec, app));
```
[travis-image]: https://img.shields.io/travis/jerolimov/bo-swag/master.svg?style=flat-square
[travis-url]: https://travis-ci.org/jerolimov/bo-swag
[coveralls-image]: https://img.shields.io/coveralls/jerolimov/bo-swag/master.svg?style=flat-square
[coveralls-url]: https://coveralls.io/r/jerolimov/bo-swag
[dependency-image]: http://img.shields.io/david/jerolimov/bo-swag.svg?style=flat-square
[dependency-url]: https://david-dm.org/jerolimov/bo-swag