mvc: versioning: add 'Deprecated' feature as well

Former-commit-id: c233bae47aa765a7e1cd9ab7000acd14614a78ae

_examples/mvc/versioned-controller/main.go

@@ -1,10 +1,19 @@
 package main
 
 import (
+	"time"
+
 	"github.com/kataras/iris/v12"
 	"github.com/kataras/iris/v12/mvc"
 )
 
+// Optional deprecated X-API-XXX headers for version 1.
+var opts = mvc.DeprecationOptions{
+	WarnMessage:     "deprecated, see <this link>",
+	DeprecationDate: time.Now().UTC(),
+	DeprecationInfo: "a bigger version is available, see <this link> for more information",
+}
+
 func main() {
 	app := newApp()
 
@@ -18,7 +27,8 @@ func newApp() *iris.Application {
 	dataRouter := app.Party("/data")
 	{
 		m := mvc.New(dataRouter)
-		m.Handle(new(v1Controller), mvc.Version("1"))       // 1 or 1.0, 1.0.0 ...
+
+		m.Handle(new(v1Controller), mvc.Version("1"), mvc.Deprecated(opts)) // 1 or 1.0, 1.0.0 ...
 		m.Handle(new(v2Controller), mvc.Version("2.3"))                     // 2.3 or 2.3.0
 		m.Handle(new(v3Controller), mvc.Version(">=3, <4"))                 // 3, 3.x, 3.x.x ...
 		m.Handle(new(noVersionController))

_examples/mvc/versioned-controller/main_test.go

@@ -18,9 +18,17 @@ func TestVersionedController(t *testing.T) {
 		Status(iris.StatusOK).Body().Equal("data (v2.x)")
 	e.GET("/data").WithHeader(versioning.AcceptVersionHeaderKey, "3.1").Expect().
 		Status(iris.StatusOK).Body().Equal("data (v3.x)")
+
 	// Test invalid version or no version at all.
 	e.GET("/data").WithHeader(versioning.AcceptVersionHeaderKey, "4").Expect().
 		Status(iris.StatusOK).Body().Equal("data")
 	e.GET("/data").Expect().
 		Status(iris.StatusOK).Body().Equal("data")
+
+	// Test Deprecated (v1)
+	ex := e.GET("/data").WithHeader(versioning.AcceptVersionHeaderKey, "1.0").Expect()
+	ex.Status(iris.StatusOK).Body().Equal("data (v1.x)")
+	ex.Header("X-API-Warn").Equal(opts.WarnMessage)
+	expectedDateStr := opts.DeprecationDate.Format(app.ConfigurationReadOnly().GetTimeFormat())
+	ex.Header("X-API-Deprecation-Date").Equal(expectedDateStr)
 }

mvc/aliases.go

@@ -1,15 +1,22 @@
 package mvc
 
-import "github.com/kataras/iris/v12/hero"
+import (
+	"github.com/kataras/iris/v12/hero"
+	"github.com/kataras/iris/v12/versioning"
+)
 
 type (
-
 	// Result is a type alias for the `hero#Result`, useful for output controller's methods.
 	Result = hero.Result
 	// Response is a type alias for the `hero#Response`, useful for output controller's methods.
 	Response = hero.Response
 	// View is a type alias for the `hero#View`, useful for output controller's methods.
 	View = hero.View
+	// DeprecationOptions describes the deprecation headers key-values.
+	// Is a type alias for the `versioning#DeprecationOptions`.
+	//
+	// See `Deprecated` package-level option.
+	DeprecationOptions = versioning.DeprecationOptions
 )
 
 // Try is a type alias for the `hero#Try`,

mvc/versioning.go

@@ -13,7 +13,7 @@ import (
 //
 // Usage:
 // 	m := mvc.New(dataRouter)
-// 	m.Handle(new(v1Controller), mvc.Version("1"))
+// 	m.Handle(new(v1Controller), mvc.Version("1"), mvc.Deprecated(mvc.DeprecationOptions{}))
 // 	m.Handle(new(v2Controller), mvc.Version("2.3"))
 // 	m.Handle(new(v3Controller), mvc.Version(">=3, <4"))
 // 	m.Handle(new(noVersionController))
@@ -36,3 +36,15 @@ func Version(version string) OptionFunc {
 		})
 	}
 }
+
+// Deprecated marks a specific Controller as a deprecated one.
+// Deprecated can be used to tell the clients that
+// a newer version of that specific resource is available instead.
+func Deprecated(options DeprecationOptions) OptionFunc {
+	return func(c *ControllerActivator) {
+		c.Use(func(ctx context.Context) {
+			versioning.WriteDeprecated(ctx, options)
+			ctx.Next()
+		})
+	}
+}

versioning/deprecation.go

@@ -27,15 +27,16 @@ var DefaultDeprecationOptions = DeprecationOptions{
 	WarnMessage: "WARNING! You are using a deprecated version of this API.",
 }
 
-// Deprecated marks a specific handler as a deprecated.
-// Deprecated can be used to tell the clients that
-// a newer version of that specific resource is available instead.
-func Deprecated(handler context.Handler, options DeprecationOptions) context.Handler {
+// WriteDeprecated writes the deprecated response headers
+// based on the given "options".
+// It can be used inside a middleware.
+//
+// See `Deprecated` to wrap an existing handler instead.
+func WriteDeprecated(ctx context.Context, options DeprecationOptions) {
 	if options.WarnMessage == "" {
 		options.WarnMessage = DefaultDeprecationOptions.WarnMessage
 	}
 
-	return func(ctx context.Context) {
 	ctx.Header("X-API-Warn", options.WarnMessage)
 
 	if !options.DeprecationDate.IsZero() {
@@ -45,7 +46,14 @@ func Deprecated(handler context.Handler, options DeprecationOptions) context.Han
 	if options.DeprecationInfo != "" {
 		ctx.Header("X-API-Deprecation-Info", options.DeprecationInfo)
 	}
+}
 
+// Deprecated marks a specific handler as a deprecated.
+// Deprecated can be used to tell the clients that
+// a newer version of that specific resource is available instead.
+func Deprecated(handler context.Handler, options DeprecationOptions) context.Handler {
+	return func(ctx context.Context) {
+		WriteDeprecated(ctx, options)
 		handler(ctx)
 	}
 }