feat(oaslint): add oaslint

api/api/v1/apicategory_types.go

@@ -13,6 +13,47 @@ import (
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 )
 
+// LintingMode controls how linting failures affect API creation.
+type LintingMode string
+
+const (
+	// LintingModeBlock prevents Api creation when linting fails.
+	LintingModeBlock LintingMode = "block"
+	// LintingModeWarn allows Api creation but surfaces linting issues in status.
+	LintingModeWarn LintingMode = "warn"
+	// LintingModeNone indicates that no linting is configured for this category.
+	LintingModeNone LintingMode = "none"
+)
+
+// LintingConfig configures OAS specification linting for APIs in this category.
+type LintingConfig struct {
+	// URL is the base URL of the external linter service.
+	// When set, linting is enabled for this category.
+	// +kubebuilder:validation:Format=uri
+	// +optional
+	URL string `json:"url,omitempty"`
+
+	// Ruleset is the name of the linter ruleset to apply.
+	// If set, it is passed as a query parameter to the linter API.
+	// +optional
+	Ruleset string `json:"ruleset,omitempty"`
+
+	// Mode controls how linting failures affect API creation.
+	// "block" (default) prevents Api creation on failure; "warn" allows it but surfaces issues.
+	// +kubebuilder:validation:Enum=block;warn;none
+	// +kubebuilder:default:=block
+	// +optional
+	Mode LintingMode `json:"mode,omitempty"`
+
+	// WhitelistedBasepaths is a list of API basepaths that are exempt from linting.
+	// APIs whose basePath matches an entry here will skip linting even when a linter URL is configured.
+	// Each entry must start with a leading slash.
+	// +optional
+	// +listType=set
+	// +kubebuilder:validation:items:Pattern=`^/`
+	WhitelistedBasepaths []string `json:"whitelistedBasepaths,omitempty"`
+}
+
 // ApiCategorySpec defines the desired state of ApiCategory
 type ApiCategorySpec struct {
 	// LabelValue is the name of the API category in the specification.
@@ -39,16 +80,12 @@ type ApiCategorySpec struct {
 	// +kubebuilder:default:=true
 	MustHaveGroupPrefix bool `json:"mustHaveGroupPrefix,omitempty"`
 
+	// Linting configures OAS specification linting for APIs in this category.
+	// If set with a URL, linting is enabled for this category.
+	// +optional
 	Linting *LintingConfig `json:"linting,omitempty"`
 }
 
-type LintingConfig struct {
-	// Enabled indicates whether linting is enabled for this API category.
-	Enabled bool `json:"enabled,omitempty"`
-	// Ruleset specifies the ruleset to use for linting.
-	Ruleset string `json:"ruleset,omitempty"`
-}
-
 type AllowTeamsConfig struct {
 	// Categories defines the list of team categories that are allowed to use this API category.
 	// If empty, all team categories are allowed.

api/config/crd/bases/api.cp.ei.telekom.de_apicategories.yaml

@@ -80,14 +80,41 @@ spec:
                 minLength: 1
                 type: string
               linting:
+                description: |-
+                  Linting configures OAS specification linting for APIs in this category.
+                  If set with a URL, linting is enabled for this category.
                 properties:
-                  enabled:
-                    description: Enabled indicates whether linting is enabled for
-                      this API category.
-                    type: boolean
+                  mode:
+                    default: block
+                    description: |-
+                      Mode controls how linting failures affect API creation.
+                      "block" (default) prevents Api creation on failure; "warn" allows it but surfaces issues.
+                    enum:
+                    - block
+                    - warn
+                    - none
+                    type: string
                   ruleset:
-                    description: Ruleset specifies the ruleset to use for linting.
+                    description: |-
+                      Ruleset is the name of the linter ruleset to apply.
+                      If set, it is passed as a query parameter to the linter API.
+                    type: string
+                  url:
+                    description: |-
+                      URL is the base URL of the external linter service.
+                      When set, linting is enabled for this category.
+                    format: uri
                     type: string
+                  whitelistedBasepaths:
+                    description: |-
+                      WhitelistedBasepaths is a list of API basepaths that are exempt from linting.
+                      APIs whose basePath matches an entry here will skip linting even when a linter URL is configured.
+                      Each entry must start with a leading slash.
+                    items:
+                      pattern: ^/
+                      type: string
+                    type: array
+                    x-kubernetes-list-type: set
                 type: object
               mustHaveGroupPrefix:
                 default: true

api/internal/controller/apicategory_controller_test.go

@@ -5,7 +5,7 @@
 package controller
 
 import (
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 	"sigs.k8s.io/controller-runtime/pkg/client"
 
@@ -34,10 +34,6 @@
 				Names:      []string{"test-team"},
 			},
 			MustHaveGroupPrefix: true,
-			Linting: &apiv1.LintingConfig{
-				Enabled: false,
-				Ruleset: "owasp",
-			},
 		},
 	}
 }

rover-server/cmd/main.go

@@ -51,7 +51,7 @@
 	s := server.Server{
 		Config:              cfg,
 		Log:                 log.Log,
-		ApiSpecifications:   controller.NewApiSpecificationController(stores),
+		ApiSpecifications:   controller.NewApiSpecificationController(stores, cfg.OasLinting.ErrorMessage, cfg.OasLinting.Timeout, cfg.OasLinting.Async),
 		Rovers:              controller.NewRoverController(stores),
 		Roadmaps:            controller.NewRoadmapController(stores),
 		EventSpecifications: controller.NewEventSpecificationController(stores),
@@ -64,7 +64,7 @@
 	signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
 	go func() {
 		err := app.Listen(cfg.Address)
 		if err != nil && err != http.ErrServerClosed {
 			log.Log.Error(err, "Failed to start server")
 		}
 	}()

rover-server/config/rbac/role.yaml

@@ -18,6 +18,7 @@ rules:
 - apiGroups:
   - api.cp.ei.telekom.de
   resources:
+  - apicategories
   - apiexposures
   - apis
   - apisubscriptions

rover-server/internal/config/config.go

@@ -6,6 +6,7 @@ package config
 
 import (
 	"strings"
+	"time"
 
 	"github.com/pkg/errors"
 	"github.com/spf13/viper"
@@ -16,6 +17,13 @@ type ServerConfig struct {
 	Security    SecurityConfig    `json:"security"`
 	Log         LogConfig         `json:"log"`
 	FileManager FileManagerConfig `json:"fileManager"`
+	OasLinting  OasLintingConfig  `json:"oasLinting"`
+}
+
+type OasLintingConfig struct {
+	ErrorMessage string        `json:"errorMessage"`
+	Timeout      time.Duration `json:"timeout"`
+	Async        bool          `json:"async"`
 }
 
 type SecurityConfig struct {
@@ -72,6 +80,11 @@ func setDefaults() {
 	// FileManager
 	viper.SetDefault("fileManager.skipTLS", true)
 
+	// OAS Linting
+	viper.SetDefault("oasLinting.errorMessage", "Linter scan result contains errors. Please visit the linter UI for details on the RULESET_NAME_PLACEHOLDER ruleset.")
+	viper.SetDefault("oasLinting.timeout", 0) // 0 means block indefinitely until linter responds
+	viper.SetDefault("oasLinting.async", false)
+
 	// Database
 	viper.SetDefault("database.filepath", "")        // empty string means in-memory only
 	viper.SetDefault("database.reduceMemory", false) // see common-server docs

rover-server/internal/controller/__snapshots__/suite_controller_test.snap

@@ -617,7 +617,7 @@
 
 [Rover Controller Get rover status should return the status of a rover successfully - 1]
 {
- "createdAt": "2025-09-18T08:39:44Z",
+ "createdAt": "2025-09-18T10:39:44+02:00",
  "errors": [
   {
    "cause": "NoApproval",
@@ -632,7 +632,7 @@
   }
  ],
  "overallStatus": "blocked",
- "processedAt": "2025-10-08T07:16:40Z",
+ "processedAt": "2025-10-08T09:16:40+02:00",
  "processingState": "done",
  "state": "blocked"
 }