SWDOGEN

This is a documentation generator for swagger-ui. It will scan your project source code, extract the comment with special beginning, parse the swagger code within the comment and generate the swagger documentation.

See the Wiki!

The github wiki contains documentation, samples, etc. Start there

Supported Language

Any languages that supports c-style bloack comment, ie.

/* 
	comments
	...
*/

How to get it

Install from OPAM

Swdogen is implemented in OCaml and managed by OPAM.

1. Install OPAM. See instructions.
2. Install Swdogen: opam install swdogen

Build from source

Download source code of Swdogen from releases or clone with git.

To build using the following commands

$ ocaml setup.ml -configure
$ ocaml setup.ml -build

To install using the following commands

$ ocaml setup.ml -install

For optional test, reconfigure with test enable

$ ocaml setup.ml -configure --enable-tests
$ ocaml setup.ml -build
$ ocaml setup.ml -test

To uninstall using the following commands

$ ocaml setup.ml -uninstall

Dependencies

If there is any missing dependency, you may install them by opam or by hand

• ounit: a unit test framework for OCaml
• atdgen: a tool that derives OCaml boilerplate code from type definitions

Usage (Just 3 steps to go)

1. create the centre config file _swdogen in the top-level of your project. For details, see the wiki.
2. Document your project with swdogen notation, a javadoc like notation.
3. run swdogen in the top-level of your project

Live Demo

There are some sample programs in the example folder. Pick the one you like and move to its top-level directory which contains a _swdogen. (eg. example/petstore)

$ cd example/petstore
$ ls
_swdogen  models  resources

and run

$ swdogen
$ ls
_swdogen  apis  models  resources

the generated swagger-ui doc would be lie in the apis folder.

Templates

There are some Templates to make your API swagger even more easier.

Contact

Problems or questions? fire an issue at github

License

The MIT License (MIT)

Copyright (c) <2013> colsy2@gmail.com

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.