feat: support operation descriptions

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)).

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,

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)
+}

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)