feat(oaslint): add oaslint

api/api/v1/apicategory_types.go

@@ -13,6 +13,41 @@ 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 {
+	// Ruleset is the name of the linter ruleset to apply.
+	// If set, it is passed as a URL-encoded query parameter to the linter API.
+	// +required
+	Ruleset string `json:"ruleset"`
+
+	// 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 linting 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 +74,11 @@ type ApiCategorySpec struct {
 	// +kubebuilder:default:=true
 	MustHaveGroupPrefix bool `json:"mustHaveGroupPrefix,omitempty"`
 
+	// Linting configures OAS specification linting for APIs in 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,36 @@ spec:
                 minLength: 1
                 type: string
               linting:
+                description: Linting configures OAS specification linting for APIs
+                  in 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 URL-encoded query parameter to the linter API.
                     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 linting is configured.
+                      Each entry must start with a leading slash.
+                    items:
+                      pattern: ^/
+                      type: string
+                    type: array
+                    x-kubernetes-list-type: set
+                required:
+                - ruleset
                 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",
-			},
 		},
 	}
 }

docs/docs/admin-journey/features/api-categories.md

@@ -140,21 +140,54 @@ When set to `false`, teams in this category can use any base path structure. The
 
 ### API linting
 
-API Categories can enforce linting on submitted OpenAPI specifications. When linting is enabled, every specification registered under this category is validated against the specified ruleset.
+API Categories can enforce linting on submitted OpenAPI specifications. When linting is configured, every specification registered under this category is validated against the specified ruleset.
 
 ```yaml
 spec:
   labelValue: "public"
   active: true
   linting:
-    enabled: true
     ruleset: "strict"
+    mode: "Block"
+    whitelistedBasepaths:
+      - "/legacy/api/v1"
 ```
 
 | Field | Description |
 | ----- | ----------- |
-| `enabled` | Turns linting on or off for this category. |
-| `ruleset` | The name of the ruleset to validate against. |
+| `ruleset` | **(required)** The name of the ruleset to validate against. Passed to the external linter as a query parameter. |
+| `mode` | `Block` (default) rejects the specification on failure; `Warn` stores the result but allows the upload; `None` disables linting. |
+| `whitelistedBasepaths` | A list of base paths that skip linting entirely (case-insensitive match). Each entry must start with `/`. |
+
+:::info
+Linting is only active when the `linting` section is present **and** `mode` is not `None`. If the `linting` section is omitted entirely, no linting is performed.
+:::
+
+#### Error message template
+
+The rover-server configuration option `oasLinting.errorMessage` controls the message returned to clients when linting fails. It supports the following placeholders:
+
+| Placeholder | Replaced with | Description |
+|---|---|---|
+| `RULESET_NAME_PLACEHOLDER` | Ruleset name from the lint result | The name of the ruleset that was applied during linting |
+
+**Default:**
+
+```
+Linter scan result contains errors. Please visit the linter UI for details on the RULESET_NAME_PLACEHOLDER ruleset.
+```
+
+#### Rover-server linting configuration
+
+The following environment variables configure the linting integration on the rover-server side:
+
+| Environment Variable | Description | Default |
+|---|---|---|
+| `OASLINTING_URL` | Base URL of the external linter API. If empty, linting is disabled regardless of category config. | _(empty)_ |
+| `OASLINTING_DASHBOARDURL` | Base URL of the linter dashboard. When set, lint results include a link to `<url>/scans/<linterId>`. | _(empty)_ |
+| `OASLINTING_ERRORMESSAGE` | Error message template (see placeholders above). | See above |
+| `OASLINTING_TIMEOUT` | HTTP timeout for linter requests (Go duration, e.g. `30s`). `0` means no timeout. | `55s` |
+| `OASLINTING_SKIPTLS` | Skip TLS verification for linter requests. | `false` |
 
 ### Activating and deactivating categories
 
@@ -186,8 +219,8 @@ spec:
     names:
       - "phoenix--firebirds"
   linting:
-    enabled: true
     ruleset: "strict"
+    mode: "Block"
 ```
 
 This category:

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),
 		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,15 @@ 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"`
+	URL          string        `json:"url"`
+	DashboardURL string        `json:"dashboardURL"`
+	SkipTLS      bool          `json:"skipTLS"`
 }
 
 type SecurityConfig struct {
@@ -72,6 +82,13 @@ func setDefaults() {
 	// FileManager
 	viper.SetDefault("fileManager.skipTLS", true)
 
+	// OAS Linting
+	viper.SetDefault("oasLinting.errorMessage", "Linter scan result contains errors for RULESET_NAME_PLACEHOLDER ruleset.")
+	viper.SetDefault("oasLinting.timeout", 55) // seconds; 0 means block indefinitely until linter responds
+	viper.SetDefault("oasLinting.url", "")
+	viper.SetDefault("oasLinting.dashboardURL", "")
+	viper.SetDefault("oasLinting.skipTLS", false)
+
 	// Database
 	viper.SetDefault("database.filepath", "")        // empty string means in-memory only
 	viper.SetDefault("database.reduceMemory", false) // see common-server docs