WORK IN PROGRESS
Easily describe your API by writing JSdoc-like golang comments that render into a RAML 1.0 file
RESTful API Modeling Language (RAML) is a YAML-based language for describing RESTful APIs. It provides all the information necessary to describe RESTful or practically RESTful APIs. Wikipedia
An API is a living thing - wether it's from a designer, a builder or a consumer point of view, maintaining a coherent and up-to-date documentation of its endpoints is mandatory.
godoc2api simplifies this process by peeping into your go code to extract and generate a structured, comprehensible API documentation.
- Overly simple to implement on existing APIs
- Binds code documentation to API behaviour for feature integrity
- Enforces good code documentation practices
- Produces a standardised and consommable output
- Code documentation + auto-generated public doc + testable API = 👍
go get github.com/florenthobein/godoc2apiFor now only RAML 1.0 specification is supported. It also mainly focuses on a full application/json API, as input and output.
Say you've defined the following route / handler
func main () {
http.HandleFunc("/myroute", myHander)
http.ListenAndServe(":8080", nil)
}
func myHander(rw http.ResponseWriter, r *http.Request) {
fmt.Fprintf(rw, "Hello world!")
}Simply add comments to your handler like this
// An endpoint that just says hi
// @resource GET /myroute
func myHander(rw http.ResponseWriter, r *http.Request) {
fmt.Fprintf(rw, "Hello world!")
}That's it! Now you can generate the documentation:
import "github.com/florenthobein/godoc2api"
func main () {
// Define your normal route
http.HandleFunc("/myroute", myHander)
// Define your documentation and save it
doc := godoc2api.Documentation{URL: "http://localhost:8080"}
doc.AddRoute(myHander)
doc.Save("example_basic/")
// Run your webserver
http.ListenAndServe(":8080", nil)
}Detailed examples are written on the godoc page, including RAML outputs.
Code in the examples folder.
todo
todo
todo
todo
todo
todo
Change the log level of the library to display warnings:
// Possible values:
// - LOG_DEBUG
// - LOG_WARN
// - LOG_ERR
// - LOG_NOTHING (default)
godoc2api.LogLevel = godoc2api.LOG_WARN- Implementation of traits
- Implementation of security schemes
- Implementation of annotations
- Exportation in multiple files & includes
- RAML structure validation
- Support for other standards
- This library is inspired by the work on github.com/Jumpscale/go-raml
- And of course, the RAML 1.0 specifications
Copyright (c) 2017 Florent Hobein. Licensed under the MIT license.