docs: enhance plugin generation and expression handling (#217)

* docs: enhance plugin generation and expression handling

- Improve docs plugin generation logic with better error handling
- Add new expression types and root handling in docs/expr
- Update DSL definitions for enhanced documentation features
- Update dependencies in go.mod and go.sum

This commit enhances the documentation plugin with improved generation
capabilities and better expression handling for more robust documentation
generation.

* fix: remove unreachable case clause in walkDeps

Remove the unreachable *goaexpr.ResultTypeExpr case since ResultTypeExpr
implements UserType interface and is already handled by the goaexpr.UserType
case. This fixes the static analysis warning SA4020.

Author: raphael

docs/dsl/docs.go

@@ -4,23 +4,58 @@ import (
 	"goa.design/goa/v3/eval"
 	goaexpr "goa.design/goa/v3/expr"
 	"goa.design/plugins/v3/docs"
-	"goa.design/plugins/v3/docs/expr"
+	plugexpr "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 }
+// Meta("struct:tag:json", ...) as field names in generated docs.
+//
+// This setting affects type definitions, payloads, results, and error schemas
+// and their examples.
+//
+// Usage:
+//
+//	var _ = API("my api", func() {
+//		// Use field names from struct JSON tags throughout docs.json
+//		docs.UseJSONTags()
+//	})
+func UseJSONTags() { plugexpr.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 }
+// Schema output where possible. Cycles are preserved by keeping $ref where
+// needed (e.g., recursive references).
+//
+// Usage:
+//
+//	var _ = API("my api", func() {
+//		// Prefer inlined schemas rather than $ref when there are no cycles
+//		docs.InlineRefs()
+//	})
+func InlineRefs() { plugexpr.Root.InlineRefs = true }
+
+// IncludeTypes registers user types to force-emit in docs.json definitions.
+// Accepts user types defined via Type or ResultType.
+//
+// Service and method schemas are always generated by the docs plugin when not
+// disabled on the service/method. IncludeTypes does not change service/method
+// emission. This is only useful for types that are generated via the "force"
+// Goa Meta DSL; it ensures those user types (and their transitive dependencies)
+// are included under the top-level "definitions" object.
+//
+// Usage:
+//
+//	var _ = API("my api", func() {
+//		// Ensure these shared types appear in docs.json definitions so downstream
+//		// tooling can resolve schemas by name.
+//		docs.IncludeTypes(MySharedType, AnotherType)
+//	})
+func IncludeTypes(ts ...goaexpr.UserType) { plugexpr.Root.IncludeTypes(ts...) }
 
-// DisableDocs disables docs.json generation for the current service only.
-// It does not affect OpenAPI generation. Invoke inside a Service DSL.
+// DisableDocs disables docs.json generation for the current service or method.
+// It does not affect OpenAPI generation. Invoke inside a Service or Method DSL.
 //
 //	Service("front", func() {
 //	    DisableDocs()

docs/expr/root.go

@@ -18,6 +18,9 @@ type (
 		// replacing them with copies of their referenced definitions where
 		// possible. Cycles are preserved by leaving $ref in place when needed.
 		InlineRefs bool
+
+		// IncludedTypes are the user types to force-emit into definitions.
+		IncludedTypes []expr.UserType
 	}
 )
 
@@ -39,3 +42,12 @@ func (*RootExpr) DependsOn() []eval.Root { return []eval.Root{expr.Root} }
 // 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"} }
+
+// IncludeTypes registers the given user types for forced definition emission.
+func (r *RootExpr) IncludeTypes(ts ...expr.UserType) {
+	for _, t := range ts {
+		if t != nil {
+			r.IncludedTypes = append(r.IncludedTypes, t)
+		}
+	}
+}