feat!: Upgrade to OpenAPI v3

Upgrading from Swagger to OpenAPI v3 offers numerous benefits, including enhanced specification features, better support for modern use cases, improved developer experience, access to a richer ecosystem and tooling, future-proofing our API specifications, and ensuring compliance and interoperability. This upgrade is a breaking change because it requires using a different code generator, resulting in changes to the generated model. Users of the Go client library will need to make minor adjustments to their code. Signed-off-by: Michael Adler <[email protected]>
siemens · Jul 26, 2024 · 3cefeed · 3cefeed
1 parent b66e132
commit 3cefeed
Show file tree

Hide file tree

Showing 328 changed files with 10,459 additions and 35,442 deletions.
diff --git a/.gitignore b/.gitignore
@@ -7,15 +7,13 @@
 /wfx-viewer
 *.pem
 *.generated
-cmd/wfx-viewer/wfx-viewer
 /public
 /result
 /dist
 /files
 coverage*
 *.log
 /results
-generated/wfx.swagger.yml
 /out
 *.cov
 /wfx.db*

diff --git a/.golangci.yml b/.golangci.yml
@@ -3,6 +3,8 @@
 # SPDX-License-Identifier: Apache-2.0
 ---
 run:
+  go: "1.22"
+
   # timeout for analysis, e.g. 30s, 5m, default is 1m
   timeout: 5m
 
@@ -19,18 +21,6 @@ run:
     - postgres
     - mysql
 
-  # default is true. Enables skipping of directories:
-  #   vendor$, third_party$, testdata$, examples$, Godeps$, builtin$
-  skip-dirs-use-default: true
-
-  # which files to skip: they will be analyzed, but issues from them
-  # won't be reported. Default value is empty list, but there is
-  # no need to include all autogenerated files, we confidently recognize
-  # autogenerated files. If it's not please let us know.
-  # "/" will be replaced by current OS file path separator to properly work
-  # on Windows.
-  skip-files: []
-
   # by default isn't set. If set we pass it to "go list -mod={option}". From "go help modules":
   # If invoked with -mod=readonly, the go command is disallowed from the implicit
   # automatic updating of go.mod described above. Instead, it fails when any changes
@@ -47,10 +37,6 @@ run:
 
 # output configuration options
 output:
-  # colored-line-number|line-number|json|tab|checkstyle|code-climate|junit-xml|github-actions
-  # default is "colored-line-number"
-  format: colored-line-number
-
   # print lines of code with issue, default is true
   print-issued-lines: true
 
@@ -92,7 +78,6 @@ linters:
 
 linters-settings:
   staticcheck:
-    go: "1.21"
     # https://staticcheck.io/docs/options#checks
     checks: ["all", "-ST1000", "-SA1019"]
   misspell:
@@ -107,3 +92,15 @@ linters-settings:
   dupword:
     keywords:
       - "INSTALLING"
+  revive:
+    rules:
+      - name: var-naming
+        severity: warning
+        disabled: false
+        exclude: [""]
+        arguments:
+          - ["ID"] # AllowList
+          - [] # DenyList
+          - - upperCaseConst: true # Extra parameter (upperCaseConst|skipPackageNameChecks)
+  stylecheck:
+    checks: ["all", "-ST1003"]
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -9,13 +9,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- `wfxctl workflow query` now accepts a `sort` param
+- Added (existing but undocumented) `/health` and `/version` endpoint to OpenAPI spec
+
 ### Fixed
 
 - `wfx` would not start if it was built without plugins support
 
 ### Changed
 
 - Use zstd instead of xz to compress release tarballs
+- Migrated from Swagger to OpenAPI v3
+- Spec endpoint is now `/openapi.json` instead of `/swagger.json`
+- `wfxctl job delete` command now accepts jobs as arguments instead of positional parameters
+- `wfxctl workflow get` uses southbound API by default
+- Forbbiden requests (e.g. job creation via southbound API) now return HTTP status code 403 instead of 405
 
 ## [0.3.1] - 2024-07-09
 

diff --git a/README.md b/README.md
@@ -58,7 +58,7 @@ An exemplary [Kanban](https://en.wikipedia.org/wiki/Kanban)-inspired [workflow](
   - Extendable modularized source code architecture
   - Lightweight, no dependencies (statically linked binaries)
   - Efficient, native code for a wide variety of platforms and operating systems (as supported by the [Go](https://golang.org/) Language)
-  - Fully documented REST API, see [wfx OpenAPI Specification](spec/wfx.swagger.yml)
+  - Fully documented REST API, see [wfx OpenAPI Specification](spec/wfx.openapi.yml)
   - Extensive test suite including load tests
 - Deployment / Usability
   - Load / Unload workflows at run-time

diff --git a/api/errors.go b/api/errors.go
@@ -8,35 +8,35 @@ package api
  * Author: Michael Adler <[email protected]>
  */
 
-import "github.com/siemens/wfx/generated/model"
+import "github.com/siemens/wfx/generated/api"
 
 /* these are defined in the swagger yaml */
 
-var InvalidRequest = model.Error{
+var InvalidRequest = api.Error{
 	Code:    "wfx.invalidRequest",
 	Message: "The request was invalid and/or could not be completed by the storage",
 	Logref:  "96a37ea1f7d205ffbfa12334c6812727",
 }
 
-var JobNotFound = model.Error{
+var JobNotFound = api.Error{
 	Code:    "wfx.jobNotFound",
 	Logref:  "11cc67762090e15b79a1387eca65ba65",
 	Message: "Job ID was not found",
 }
 
-var WorkflowNotFound = model.Error{
+var WorkflowNotFound = api.Error{
 	Code:    "wfx.workflowNotFound",
 	Logref:  "c452719774086b6e803bb8f6ecea9899",
 	Message: "Workflow not found for given name",
 }
 
-var WorkflowNotUnique = model.Error{
+var WorkflowNotUnique = api.Error{
 	Code:    "wfx.workflowNotUnique",
 	Logref:  "e1ee1f2aea859b9dd34579610e386da6",
 	Message: "Workflow with name already exists",
 }
 
-var WorkflowInvalid = model.Error{
+var WorkflowInvalid = api.Error{
 	Code:    "wfx.workflowInvalid",
 	Logref:  "18f57adc70dd79c7fb4f1246be8a6e04",
 	Message: "Workflow validation failed",

diff --git a/api/job_events_test.go b/api/job_events_test.go
@@ -23,7 +23,7 @@ import (
 	"github.com/rs/zerolog"
 	"github.com/rs/zerolog/log"
 
-	"github.com/siemens/wfx/generated/model"
+	"github.com/siemens/wfx/generated/api"
 	"github.com/siemens/wfx/internal/handler/job"
 	"github.com/siemens/wfx/internal/handler/job/events"
 	"github.com/siemens/wfx/internal/handler/job/status"
@@ -74,7 +74,7 @@ func TestJobEventsSubscribe(t *testing.T) {
 				events.ShutdownSubscribers()
 			}()
 
-			_, err := job.CreateJob(context.Background(), db, &model.JobRequest{ClientID: clientID, Workflow: wf.Name})
+			_, err := job.CreateJob(context.Background(), db, &api.JobRequest{ClientID: clientID, Workflow: wf.Name})
 			require.NoError(t, err)
 
 			wg.Add(1)
@@ -85,7 +85,7 @@ func TestJobEventsSubscribe(t *testing.T) {
 					time.Sleep(20 * time.Millisecond)
 				}
 				// update job
-				_, err = status.Update(context.Background(), db, *jobID.Load(), &model.JobStatus{State: "INSTALLING"}, model.EligibleEnumCLIENT)
+				_, err = status.Update(context.Background(), db, *jobID.Load(), &api.JobStatus{State: "INSTALLING"}, api.CLIENT)
 				require.NoError(t, err)
 			}()
 

diff --git a/api/job_id_test.go b/api/job_id_test.go
@@ -14,7 +14,6 @@ import (
 	"net/http"
 	"testing"
 
-	"github.com/siemens/wfx/middleware/jq"
 	"github.com/siemens/wfx/persistence"
 	"github.com/steinfletcher/apitest"
 	jsonpath "github.com/steinfletcher/apitest-jsonpath"
@@ -47,9 +46,6 @@ func TestJobGetIdFilter(t *testing.T) {
 	job := persistJob(t, db)
 	jobPath := fmt.Sprintf("/api/wfx/v1/jobs/%s", job.ID)
 
-	north = jq.MW{}.Wrap(north)
-	south = jq.MW{}.Wrap(south)
-
 	// read job
 	handlers := []http.Handler{north, south}
 	for i, name := range allAPIs {
@@ -94,7 +90,7 @@ func TestDeleteJob(t *testing.T) {
 		Delete(jobPath).
 		ContentType("application/json").
 		Expect(t).
-		Status(http.StatusMethodNotAllowed).
+		Status(http.StatusForbidden).
 		End()
 
 	// delete job shall succeed for north

diff --git a/api/job_status_test.go b/api/job_status_test.go
@@ -14,7 +14,7 @@ import (
 	"net/http"
 	"testing"
 
-	"github.com/siemens/wfx/generated/model"
+	"github.com/siemens/wfx/generated/api"
 	"github.com/siemens/wfx/internal/handler/job"
 	"github.com/siemens/wfx/internal/handler/workflow"
 	"github.com/siemens/wfx/workflow/dau"
@@ -66,7 +66,7 @@ func TestJobStatusUpdate(t *testing.T) {
 	wf, err := workflow.CreateWorkflow(context.Background(), db, dau.PhasedWorkflow())
 	require.NoError(t, err)
 
-	jobReq := model.JobRequest{
+	jobReq := api.JobRequest{
 		ClientID: "foo",
 		Workflow: wf.Name,
 	}

diff --git a/api/job_tag_test.go b/api/job_tag_test.go
@@ -14,7 +14,7 @@ import (
 	"net/http"
 	"testing"
 
-	"github.com/siemens/wfx/generated/model"
+	"github.com/siemens/wfx/generated/api"
 	"github.com/siemens/wfx/internal/handler/job"
 	"github.com/siemens/wfx/internal/handler/workflow"
 	"github.com/siemens/wfx/workflow/dau"
@@ -29,7 +29,7 @@ func TestJobTagGet(t *testing.T) {
 	wf, err := workflow.CreateWorkflow(context.Background(), db, dau.DirectWorkflow())
 	require.NoError(t, err)
 
-	jobReq := model.JobRequest{
+	jobReq := api.JobRequest{
 		ClientID: "foo",
 		Workflow: wf.Name,
 		Tags:     []string{"foo", "bar"},
@@ -59,7 +59,7 @@ func TestJobTagPost(t *testing.T) {
 	wf, err := workflow.CreateWorkflow(context.Background(), db, dau.DirectWorkflow())
 	require.NoError(t, err)
 
-	jobReq := model.JobRequest{
+	jobReq := api.JobRequest{
 		ClientID: "foo",
 		Workflow: wf.Name,
 		Tags:     []string{"tag1"},
@@ -85,8 +85,10 @@ func TestJobTagPost(t *testing.T) {
 		apitest.New().
 			Handler(south).
 			Post(jobPath).
+			ContentType("application/json").
+			Body(`["bar", "foo"]`).
 			Expect(t).
-			Status(http.StatusMethodNotAllowed).
+			Status(http.StatusForbidden).
 			End()
 	})
 }
@@ -98,7 +100,7 @@ func TestJobTagDelete(t *testing.T) {
 	wf, err := workflow.CreateWorkflow(context.Background(), db, dau.DirectWorkflow())
 	require.NoError(t, err)
 
-	jobReq := model.JobRequest{
+	jobReq := api.JobRequest{
 		ClientID: "foo",
 		Workflow: wf.Name,
 		Tags:     []string{"foo", "bar"},
@@ -124,8 +126,10 @@ func TestJobTagDelete(t *testing.T) {
 		apitest.New().
 			Handler(south).
 			Delete(jobPath).
+			ContentType("application/json").
+			Body(`["foo"]`).
 			Expect(t).
-			Status(http.StatusMethodNotAllowed).
+			Status(http.StatusForbidden).
 			End()
 	})
 }
diff --git a/api/jobs_test.go b/api/jobs_test.go
@@ -14,7 +14,7 @@ import (
 	"net/http"
 	"testing"
 
-	"github.com/siemens/wfx/generated/model"
+	"github.com/siemens/wfx/generated/api"
 	"github.com/siemens/wfx/internal/handler/workflow"
 	"github.com/siemens/wfx/persistence"
 	"github.com/siemens/wfx/workflow/dau"
@@ -30,14 +30,12 @@ func TestGetJobsHandler_Group(t *testing.T) {
 	workflow, err := db.CreateWorkflow(context.Background(), dau.DirectWorkflow())
 	require.NoError(t, err)
 
-	_, err = db.CreateJob(context.Background(), &model.Job{
+	_, err = db.CreateJob(context.Background(), &api.Job{
 		ClientID: "foo",
-		Status: &model.JobStatus{
-			State:    "INSTALL",
-			Progress: 0,
-			Message:  "",
+		Status: &api.JobStatus{
+			State: "INSTALL",
 		},
-		Workflow: &model.Workflow{Name: workflow.Name},
+		Workflow: &api.Workflow{Name: workflow.Name},
 	})
 	assert.NoError(t, err)
 
@@ -111,6 +109,6 @@ func TestCreateJob_SouthNotAllowed(t *testing.T) {
 		Body(`{"clientId":"gotest","workflow":"wfx.workflow.kanban","tags":[]}`).
 		ContentType("application/json").
 		Expect(t).
-		Status(http.StatusMethodNotAllowed).
+		Status(http.StatusForbidden).
 		End()
 }