diff --git a/example_test.go b/example_test.go index 85608a2..3da834e 100644 --- a/example_test.go +++ b/example_test.go @@ -23,6 +23,7 @@ func Example() { op := openapi.Op(). ID("test-id"). Doc("test"). + Describe("Implements an example endpoint."). Tag("test-tag"). Param(openapi.PathParameter("name", "the item name")). Param(openapi.QueryParameter("filter", "the filter number", 123)). diff --git a/gen.go b/gen.go index f71c0ca..cfcec99 100644 --- a/gen.go +++ b/gen.go @@ -110,6 +110,7 @@ func (g *generator) AddOperation(method, path string, op Operation) error { g.doc.AddOperation(path, method, &kin.Operation{ Summary: op.doc, + Description: op.description, OperationID: op.id, Tags: op.tags, Deprecated: op.deprecated, diff --git a/gen_test.go b/gen_test.go index 56649fa..94982da 100644 --- a/gen_test.go +++ b/gen_test.go @@ -237,3 +237,33 @@ func (TestObject) Enums() map[string][]string { "test4": {"192.168.1.0", "192.168.1.1"}, } } + +func TestDescribeField(t *testing.T) { + mux := chi.NewMux() + + mux.Use(openapi.Op().Build()) + + mux.Route("/api", func(r chi.Router) { + op := openapi.Op(). + ID("create-multiple-ips"). + Doc("Creates multiple IPs"). + Describe("Does not support partial success, if there is a single error none are created.") + + r.With(op.Build()).Post("/ips", func(rw http.ResponseWriter, req *http.Request) {}) + }) + + doc, err := openapi.BuildSpec(mux, openapi.SpecConfig{ + ObjPkgSegments: 1, + }) + require.NoError(t, err) + + ops := doc.Paths.Value("/api/ips").Operations() + require.Len(t, ops, 1) + require.Contains(t, ops, "POST") + + opValue := ops["POST"] + require.NotNil(t, opValue) + assert.Equal(t, "create-multiple-ips", opValue.OperationID) + assert.Equal(t, "Creates multiple IPs", opValue.Summary) + assert.Equal(t, "Does not support partial success, if there is a single error none are created.", opValue.Description) +} diff --git a/op.go b/op.go index 1b75bd4..dd43a1e 100644 --- a/op.go +++ b/op.go @@ -138,16 +138,17 @@ var ( // Operation documents a request. type Operation struct { - id string - tags []string - doc string - params []Parameter - consumes []string - reads any - produces []string - returns []Response - security map[string]Security - deprecated bool + id string + tags []string + doc string + description string + params []Parameter + consumes []string + reads any + produces []string + returns []Response + security map[string]Security + deprecated bool } // Merge merges the operation with the given operation. @@ -158,6 +159,9 @@ func (o Operation) Merge(newOp Operation) Operation { if newOp.doc != "" { o.doc = newOp.doc } + if newOp.description != "" { + o.description = newOp.description + } if newOp.deprecated { o.deprecated = true } @@ -215,6 +219,12 @@ func (o *OpBuilder) Doc(doc string) *OpBuilder { return o } +// Describe sets the operation Description (long explanation). +func (o *OpBuilder) Describe(desc string) *OpBuilder { + o.op.description = desc + return o +} + // Tag appends the given tag to the operation. func (o *OpBuilder) Tag(tag string) *OpBuilder { o.op.tags = append(o.op.tags, tag)