feat(docs): update documentation generation and examples (#212)

Author: raphael

docs/README.md

@@ -113,6 +113,41 @@ Enabling the plugin changes the behavior of the `gen` command of the `goa` tool.
 The command generates an additional `docs.json` at the top level containing the
 documentation.
 
+### Respecting openapi:generate metadata
+
+The docs plugin respects Goa's `Meta("openapi:generate", "false")` (and legacy `"swagger:generate"`) to control documentation generation:
+
+- Service-level: adding `Meta("openapi:generate", "false")` to a `Service` excludes that service from `docs.json`.
+- Method-level: adding `Meta("openapi:generate", "false")` to a `Method` excludes that method from `docs.json`.
+- HTTP-level: the same meta can be set inside `HTTP(...)` blocks for services or methods and will be honored.
+
+This mirrors Goa's OpenAPI generation semantics.
+
+### Disabling docs.json per service or method
+
+To disable inclusion in `docs.json` without affecting OpenAPI generation, use the docs DSL `DisableDocs()` inside a service or method DSL:
+
+```go
+import (
+  . "goa.design/plugins/v3/docs/dsl"
+  . "goa.design/goa/v3/dsl"
+)
+
+var _ = Service("front", func() {
+  DisableDocs() // service omitted from docs.json, OpenAPI still generated
+  Method("about", func() { /* ... */ })
+})
+
+var _ = Service("S", func() {
+  Method("M1", func() {
+    DisableDocs() // method omitted from docs.json, OpenAPI still generated
+    /* ... */
+  })
+})
+```
+
+Under the hood, `DisableDocs()` sets `Meta("docs:generate", "false")`; the plugin filters those out when building docs.json.
+
 ## Known Limitations
 
 If `goa gen` is invoked with a custom output path (i.e. with the `-o` argument)

docs/dsl/docs.go

@@ -1,6 +1,8 @@
 package dsl
 
 import (
+	"goa.design/goa/v3/eval"
+	goaexpr "goa.design/goa/v3/expr"
 	"goa.design/plugins/v3/docs"
 	"goa.design/plugins/v3/docs/expr"
 )
@@ -16,3 +18,25 @@ func UseJSONTags() { expr.Root.UseJSONTags = true }
 // InlineRefs configures the docs plugin to inline referenced schemas in JSON
 // Schema output where possible. Cycles are preserved by keeping $ref.
 func InlineRefs() { expr.Root.InlineRefs = true }
+
+// DisableDocs disables docs.json generation for the current service only.
+// It does not affect OpenAPI generation. Invoke inside a Service DSL.
+//
+//	Service("front", func() {
+//	    DisableDocs()
+//	    // ... methods ...
+//	})
+func DisableDocs() {
+	switch cur := eval.Current().(type) {
+	case *goaexpr.ServiceExpr:
+		if cur.Meta == nil {
+			cur.Meta = make(goaexpr.MetaExpr)
+		}
+		cur.Meta["docs:generate"] = []string{"false"}
+	case *goaexpr.MethodExpr:
+		if cur.Meta == nil {
+			cur.Meta = make(goaexpr.MetaExpr)
+		}
+		cur.Meta["docs:generate"] = []string{"false"}
+	}
+}