Why another API package?
- There are many REST API autodocumented packages, but not for JSON-pure or TCP
- You may want use JSON, XML or YAML format over any transport (WebSocket, HTTP, TCP, UDP, etc)
- API will be automatically documented
Simple example
package main
import (
"encoding/xml"
"fmt"
"time"
sedoc "github.com/nsemikov/go-sedoc"
)
const (
MyAppName = "MyService"
MyAppVersion = "0.1.0"
)
func main() {
// create api
api := sedoc.New()
api.Description = "My self documented API"
// create commands
infoCmd := sedoc.Command{
Name: "info",
Handler: func(c sedoc.Context) error {
c.Response().Result = fmt.Sprintf("%s v%s", MyAppName, MyAppVersion)
return nil
},
}
// add examples to command (optionaly)
infoCmd.Examples = sedoc.Examples{
sedoc.Example{
Name: "simple",
Request: sedoc.ExampleRequest{
Object: sedoc.Request{
Datetime: func() time.Time { t, _ := time.Parse(time.RFC3339, "2018-10-16T09:58:03.487508407Z"); return t }(),
Command: "info",
},
},
Responses: sedoc.ExampleResponses{
sedoc.ExampleResponse{
Name: "simple",
Object: sedoc.Response{
Datetime: func() time.Time { t, _ := time.Parse(time.RFC3339, "2018-10-16T09:58:03.487508407Z"); return t }(),
Command: "info",
Result: "MyService v0.1.0",
},
},
},
},
}
// add command to api
api.AddCommand(infoCmd)
// create request
request := sedoc.NewRequest()
request.Command = "help"
// and execute it
response := api.Execute(request)
// ...
if b, err := xml.MarshalIndent(response, "", " "); err != nil {
log.Fatal(err)
} else {
log.Println(string(b))
}
}This simple example will print to stdout something like this:
<response datetime="2018-11-10T16:51:30.41952529Z" command="help">
<result description="My self documented API">
<request_format required="1" count="7">
<arg name="id" type="string" description="Request identifier (for debugging)"></arg>
<arg name="datetime" type="string" description="Datetime string (ISO 8601)"></arg>
<arg name="session" type="uuid" description="Session token uuid, formatted like "01234567-89ab-cdef-0123-456789abcdef""></arg>
<arg name="command" type="string" description="Command name string" required="true"></arg>
<arg name="args" type="object" description="Extra request parameters, one-level object"></arg>
<arg name="where" type="array" description="Search item(s) parameters, simple Array of one-level objects"></arg>
<arg name="set" type="object" description="Item(s) data to set, one-level object"></arg>
</request_format>
<response_format required="1" count="7">
<arg name="id" type="string" description="Request identifier (for debugging)"></arg>
<arg name="datetime" type="string" description="Datetime string (ISO 8601)"></arg>
<arg name="session" type="uuid" description="Session token uuid, formatted like "01234567-89ab-cdef-0123-456789abcdef""></arg>
<arg name="command" type="string" description="Command name string" required="true"></arg>
<arg name="args" type="object" description="Extra request parameters, one-level object"></arg>
<arg name="result" type="object" description="Result object. For XML maybe used another name"></arg>
<arg name="error" type="object" description="Error object. Contains `code` and `desc` fields"></arg>
</response_format>
<commands count="2">
<command name="help" description="Get list of commands">
<examples count="1">
<example name="simple help" description="simple help command usage example">
<request>
<request datetime="2018-10-16T09:58:03.487508407Z" command="help"></request>
</request>
</example>
</examples>
</command>
<command name="info" description="">
<examples count="1">
<example name="simple">
<request>
<request datetime="2018-10-16T09:58:03.487508407Z" command="info"></request>
</request>
<responses count="1">
<response name="simple">
<response datetime="2018-10-16T09:58:03.487508407Z" command="info">
<result>MyService v0.1.0</result>
</response>
</response>
</responses>
</example>
</examples>
</command>
</commands>
<errors>
<error code="1" desc="unknown error occurred"></error>
<error code="2" desc="can't parse request"></error>
<error code="3" desc="unknown command"></error>
<error code="4" desc="invalid command argument parameter regexp"></error>
<error code="5" desc="match command argument parameter regexp fails"></error>
<error code="6" desc="require command argument parameter missing"></error>
<error code="7" desc="unknown command argument parameter in request"></error>
<error code="8" desc="invalid command argument parameter value"></error>
</errors>
</result>
</response>
