feat(docs): enhance documentation generation with JSON tags and inline references

docs/README.md

@@ -98,16 +98,14 @@ agnostic documentation in the form of a JSON document structured as follows:
 
 ## Enabling the Plugin
 
-To enable the plugin simply import both the `docs` package as follows:
+To enable the plugin, import the docs DSL package in your design. Importing the DSL also registers the plugin automatically:
 
 ```go
 import (
-  _ "goa.design/plugins/v3/docs"
+  . "goa.design/plugins/v3/docs/dsl"
   . "goa.design/goa/v3/dsl"
 )
 ```
-Note the use of blank identifier to import the `docs` package which is necessary
-as the package is imported solely for its side-effects (initialization).
 
 ## Effects on Code Generation
 
@@ -121,3 +119,34 @@ If `goa gen` is invoked with a custom output path (i.e. with the `-o` argument)
 then the plugin appends to any pre-existing `doc.json` file instead of
 overwriting. Make sure to delete the file prior to running `goa gen` when using
 the `-o` option.
+
+### Using JSON tags as field names
+
+By default, the generated documentation uses attribute names as field names in definitions and examples. To instead use JSON struct tags declared via the `Meta("struct:tag:json", ...)` DSL, enable it in your design using the docs DSL (which also registers the plugin):
+
+```go
+import (
+  . "goa.design/plugins/v3/docs/dsl"
+  . "goa.design/goa/v3/dsl"
+)
+
+func init() {
+  UseJSONTags()
+}
+```
+
+When enabled, object property names in `definitions`, payloads, results, and error schemas/examples are renamed to match their JSON tag (the part before the first comma, e.g. `name,omitempty` becomes `name`). Fields tagged with `"-"` are ignored for renaming and keep their original names. The transformation does not mutate the Goa OpenAPI global definitions.
+
+### Inlining $refs in JSON Schema
+
+To inline `$ref` schemas where possible (while preserving cycles), enable it via the docs DSL:
+
+```go
+import (
+  . "goa.design/plugins/v3/docs/dsl"
+)
+
+func init() {
+  InlineRefs()
+}
+```

docs/dsl/docs.go

@@ -0,0 +1,18 @@
+package dsl
+
+import (
+	"goa.design/plugins/v3/docs"
+	"goa.design/plugins/v3/docs/expr"
+)
+
+// init registers the docs plugin when importing the DSL.
+func init() { docs.Register() }
+
+// UseJSONTags configures the docs plugin to use JSON struct tags declared via
+// Meta("struct:tag:json", ...) as field names in generated docs. This setting
+// affects definitions, payloads, results, and error schemas and examples.
+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 }

docs/expr/root.go

@@ -0,0 +1,41 @@
+package expr
+
+import (
+	"goa.design/goa/v3/eval"
+	"goa.design/goa/v3/expr"
+)
+
+// Root is the design root expression for the docs plugin.
+var Root = &RootExpr{}
+
+type (
+	// RootExpr keeps track of docs plugin configuration toggles.
+	RootExpr struct {
+		// UseJSONTags instructs the docs generator to use JSON struct tags
+		// specified via Meta ("struct:tag:json") as field names.
+		UseJSONTags bool
+		// InlineRefs instructs the docs generator to inline $ref schemas by
+		// replacing them with copies of their referenced definitions where
+		// possible. Cycles are preserved by leaving $ref in place when needed.
+		InlineRefs bool
+	}
+)
+
+// Register design root with eval engine.
+func init() {
+	_ = eval.Register(Root)
+}
+
+// EvalName returns the name used in error messages.
+func (r *RootExpr) EvalName() string { return "Docs plugin" }
+
+// WalkSets implements eval.Root. No-op; configuration is global.
+func (*RootExpr) WalkSets(eval.SetWalker) {}
+
+// DependsOn tells the eval engine to run the goa DSL first.
+func (*RootExpr) DependsOn() []eval.Root { return []eval.Root{expr.Root} }
+
+// Packages returns the import path to the Go packages that make up the DSL.
+// This is used to skip frames that point to files in these packages when
+// computing the location of errors.
+func (*RootExpr) Packages() []string { return []string{"goa.design/plugins/v3/docs/dsl"} }