Experimental: Support API Blueprint output

Author: tcnksm

_example/doc/apib/validate.apib

@@ -0,0 +1,41 @@
+# Example API (with validation)
+
+# POST /v1/user
+Create a new user
++ Name - User Name
++ Email - User email address
++ Attribute.Birthday - User birthday YYYY-MM-DD format
+
+
++ Parameters
+  + pretty - Pretty print response message
+  + token - Request token
+
++ Request (application/json)
+
+  + Headers
+        X-Version: 2
+
+
+  + Body
+      {
+ "name": "tcnksm",
+ "email": "tcnksm@mercari.com",
+ "attribute": {
+  "birthday": "1988-11-24"
+ }
+}
+
++ Response 200
+
+  + Headers
+        Content-Type: application/json
+
+
+  + Body
+      {
+ "id": 11241988,
+ "name": "tcnksm"
+}
+
+

_example/handler_validate_test.go

@@ -19,6 +19,12 @@ func TestUserHandlerWithValidate(t *testing.T) {
 		if err := document.Generate("doc/validate.md"); err != nil {
 			t.Fatalf("err: %s", err)
 		}
+
+		// This is still experimental.
+		document.Template = httpdoc.ExperimentalTmplAPIBlueprint
+		if err := document.Generate("doc/apib/validate.apib"); err != nil {
+			t.Fatalf("err: %s", err)
+		}
 	}()
 
 	mux := http.NewServeMux()

httpdoc.go

@@ -33,8 +33,8 @@ type Document struct {
 	// This is exported just for templating.
 	Entries []Entry
 
-	// tmpl is template file to use. Currently this is only static/tmpl/doc.md.tmpl
-	tmpl string
+	// Template is template file to use. Default is TmplMarkdown.
+	Template string
 
 	logger *log.Logger
 }

static/bindata.go

@@ -0,0 +1,32 @@
+# {{ .Name }}
+
+{{ range .Entries -}}
+
+# {{ .Method }} {{ .Path }}
+{{ .Description }}
+{{ if .RequestFields -}}
+{{ range .RequestFields -}}
++ {{ .Name }} - {{ .Description }}
+{{ end }}
+{{ end }}
+{{ if .RequestParams -}}
++ Parameters
+{{ range .RequestParams }}  + {{ .Name }} - {{ .Description }}
+{{ end }}{{ end }}
++ Request (application/json)
+{{ if .RequestHeaders }}
+  + Headers
+{{ range .RequestHeaders }}        {{ .Name }}: {{ .Value }}
+{{ end }}
+{{ end }}
+  + Body
+      {{ .RequestExample }}
++ Response {{ .ResponseStatusCode }}
+{{ if .ResponseHeaders }}
+  + Headers
+{{ range .ResponseHeaders }}        {{ .Name }}: {{ .Value }}
+{{ end }}
+{{ end }}
+  + Body
+      {{ .ResponseExample }}
+{{ end }}

static/tmpl/api-blueprint.tmpl

@@ -10,8 +10,17 @@ import (
 	"github.com/mercari/go-httpdoc/static"
 )
 
+const (
+	// TmplMarkdown is markdown tempalte.
+	TmplMarkdown = "tmpl/markdown.tmpl"
+
+	// ExperimentalTmplAPIBlueprint is experimental support for API blueprint template.
+	// This maybe be modified or deleted.
+	ExperimentalTmplAPIBlueprint = "tmpl/api-blueprint.tmpl"
+)
+
 // defaultTmpl is default template file to use.
-var defaultTmpl = "tmpl/doc.md.tmpl"
+var defaultTmpl = TmplMarkdown
 
 // Generate writes documentation into the given file. Generation is skipped
 // if EnvHTTPDoc is empty. If directory does not exist or any, it returns error.
@@ -32,11 +41,11 @@ func (d *Document) Generate(path string) error {
 }
 
 func (d *Document) generate(w io.Writer) error {
-	if d.tmpl == "" {
-		d.tmpl = defaultTmpl
+	if d.Template == "" {
+		d.Template = defaultTmpl
 	}
 
-	buf, err := static.Asset(d.tmpl)
+	buf, err := static.Asset(d.Template)
 	if err != nil {
 		return err
 	}

static/tmpl/doc.md.tmpl static/tmpl/markdown.tmplstatic/tmpl/doc.md.tmpl renamed to static/tmpl/markdown.tmpl

@@ -92,7 +92,7 @@ func TestTemplateGenerate_InvalidPath(t *testing.T) {
 
 func TestTemplateGenerate_InvalidTmpl(t *testing.T) {
 	doc := &Document{
-		tmpl: "no-such-template",
+		Template: "no-such-template",
 	}
 	if err := doc.generate(ioutil.Discard); err == nil {
 		t.Fatalf("expect to be failed")