improve API docs linter (#3608)

.github/workflows/code_lint.yml

@@ -33,9 +33,7 @@ jobs:
       with:
         go-version: "1.22"
 
-    - run: |
-        go mod tidy
-        git diff --exit-code
+    - run: make lint-mod-tidy
 
   api_docs:
     runs-on: ubuntu-22.04
@@ -43,4 +41,4 @@ jobs:
     steps:
     - uses: actions/checkout@v3
 
-    - run: make apidocs-lint
+    - run: make lint-apidocs

.github/workflows/release.yml

@@ -137,7 +137,7 @@ jobs:
     steps:
     - uses: actions/checkout@v3
 
-    - run: make apidocs-gen
+    - run: make apidocs
 
     - run: mv apidocs/*.html apidocs/index.html
 

Makefile

@@ -20,8 +20,7 @@ help:
 	@echo "  lint             run linters"
 	@echo "  bench NAME=n     run bench environment"
 	@echo "  run              run app"
-	@echo "  apidocs-lint     run api docs linters"
-	@echo "  apidocs-gen      generate api docs HTML"
+	@echo "  apidocs          generate api docs HTML"
 	@echo "  binaries         build binaries for all platforms"
 	@echo "  dockerhub        build and push images to Docker Hub"
 	@echo "  dockerhub-legacy build and push images to Docker Hub (legacy)"

internal/testapidocs/apidocs_test.go

@@ -0,0 +1,154 @@
+package main
+
+import (
+	"os"
+	"reflect"
+	"sort"
+	"strings"
+	"testing"
+
+	"github.com/bluenviron/mediamtx/internal/conf"
+	"github.com/bluenviron/mediamtx/internal/conf/yaml"
+	"github.com/bluenviron/mediamtx/internal/defs"
+	"github.com/stretchr/testify/require"
+)
+
+func TestAPIDocs(t *testing.T) {
+	byts, err := os.ReadFile("../../apidocs/openapi.yaml")
+	require.NoError(t, err)
+
+	var raw map[string]interface{}
+	err = yaml.Load(byts, &raw)
+	require.NoError(t, err)
+
+	components := raw["components"].(map[string]interface{})
+	schemas := components["schemas"].(map[string]interface{})
+
+	for _, ca := range []struct {
+		yamlKey  string
+		goStruct interface{}
+	}{
+		{
+			"AuthInternalUser",
+			conf.AuthInternalUser{},
+		},
+		{
+			"AuthInternalUserPermission",
+			conf.AuthInternalUserPermission{},
+		},
+		{
+			"GlobalConf",
+			conf.Conf{},
+		},
+		{
+			"PathConf",
+			conf.Path{},
+		},
+		{
+			"PathConfList",
+			defs.APIPathConfList{},
+		},
+		{
+			"Path",
+			defs.APIPath{},
+		},
+		{
+			"PathList",
+			defs.APIPathList{},
+		},
+		{
+			"PathSource",
+			defs.APIPathSourceOrReader{},
+		},
+		{
+			"PathReader",
+			defs.APIPathSourceOrReader{},
+		},
+		{
+			"HLSMuxer",
+			defs.APIHLSMuxer{},
+		},
+		{
+			"HLSMuxerList",
+			defs.APIHLSMuxerList{},
+		},
+		{
+			"Recording",
+			defs.APIRecording{},
+		},
+		{
+			"RecordingList",
+			defs.APIRecordingList{},
+		},
+		{
+			"RecordingSegment",
+			defs.APIRecordingSegment{},
+		},
+		{
+			"RTMPConn",
+			defs.APIRTMPConn{},
+		},
+		{
+			"RTMPConnList",
+			defs.APIRTMPConnList{},
+		},
+		{
+			"RTSPConn",
+			defs.APIRTSPConn{},
+		},
+		{
+			"RTSPConnList",
+			defs.APIRTSPConnsList{},
+		},
+		{
+			"RTSPSession",
+			defs.APIRTSPSession{},
+		},
+		{
+			"RTSPSessionList",
+			defs.APIRTSPSessionList{},
+		},
+		{
+			"SRTConn",
+			defs.APISRTConn{},
+		},
+		{
+			"SRTConnList",
+			defs.APISRTConnList{},
+		},
+		{
+			"WebRTCSession",
+			defs.APIWebRTCSession{},
+		},
+		{
+			"WebRTCSessionList",
+			defs.APIWebRTCSessionList{},
+		},
+	} {
+		t.Run(ca.yamlKey, func(t *testing.T) {
+			yamlContent := schemas[ca.yamlKey].(map[string]interface{})
+			props := yamlContent["properties"].(map[string]interface{})
+			key1 := make([]string, len(props))
+			i := 0
+			for key := range props {
+				key1[i] = key
+				i++
+			}
+
+			var key2 []string
+			ty := reflect.TypeOf(ca.goStruct)
+			for i := 0; i < ty.NumField(); i++ {
+				sf := ty.Field(i)
+				js := sf.Tag.Get("json")
+				if js != "-" && js != "paths" && js != "pathDefaults" && !strings.Contains(js, ",omitempty") {
+					key2 = append(key2, js)
+				}
+			}
+
+			sort.Strings(key1)
+			sort.Strings(key2)
+
+			require.Equal(t, key1, key2)
+		})
+	}
+}

internal/testhighlevel/build_images_test.go

@@ -1,7 +1,7 @@
 //go:build enable_highlevel_tests
 // +build enable_highlevel_tests
 
-package highleveltests
+package testhighlevel
 
 import (
 	"os"

internal/testhighlevel/hls_manager_test.go

@@ -1,7 +1,7 @@
 //go:build enable_highlevel_tests
 // +build enable_highlevel_tests
 
-package highleveltests
+package testhighlevel
 
 import (
 	"net/http"

internal/testhighlevel/rtsp_server_test.go

@@ -1,7 +1,7 @@
 //go:build enable_highlevel_tests
 // +build enable_highlevel_tests
 
-package highleveltests
+package testhighlevel
 
 import (
 	"os"

internal/testhighlevel/tests_test.go

@@ -1,7 +1,7 @@
 //go:build enable_highlevel_tests
 // +build enable_highlevel_tests
 
-package highleveltests
+package testhighlevel
 
 import (
 	"os"

scripts/apidocs.mk

@@ -1,21 +1,10 @@
-define DOCKERFILE_APIDOCS_LINT
-FROM $(NODE_IMAGE)
-RUN yarn global add @redocly/cli@1.0.0-beta.123
-endef
-export DOCKERFILE_APIDOCS_LINT
-
-apidocs-lint:
-	echo "$$DOCKERFILE_APIDOCS_LINT" | docker build . -f - -t temp
-	docker run --rm -v $(PWD)/apidocs:/s -w /s temp \
-	sh -c "openapi lint openapi.yaml"
-
 define DOCKERFILE_APIDOCS_GEN
 FROM $(NODE_IMAGE)
 RUN yarn global add redoc-cli@0.13.7
 endef
 export DOCKERFILE_APIDOCS_GEN
 
-apidocs-gen:
+apidocs:
 	echo "$$DOCKERFILE_APIDOCS_GEN" | docker build . -f - -t temp
 	docker run --rm -v $(PWD)/apidocs:/s -w /s temp \
 	sh -c "redoc-cli bundle openapi.yaml"

scripts/lint.mk

@@ -1,5 +1,22 @@
-lint:
+define DOCKERFILE_APIDOCS_LINT
+FROM $(NODE_IMAGE)
+RUN yarn global add @redocly/cli@1.0.0-beta.123
+endef
+export DOCKERFILE_APIDOCS_LINT
+
+lint-golangci:
 	touch internal/servers/hls/hls.min.js
 	docker run --rm -v $(PWD):/app -w /app \
 	$(LINT_IMAGE) \
 	golangci-lint run -v
+
+lint-mod-tidy:
+	go mod tidy
+	git diff --exit-code
+
+lint-apidocs:
+	echo "$$DOCKERFILE_APIDOCS_LINT" | docker build . -f - -t temp
+	docker run --rm -v $(PWD)/apidocs:/s -w /s temp \
+	sh -c "openapi lint openapi.yaml"
+
+lint: lint-golangci lint-mod-tidy lint-apidocs

scripts/test-highlevel.mk

@@ -1,6 +1,6 @@
 test-highlevel-nodocker:
 	go generate ./...
-	go test -v -race -tags enable_highlevel_tests ./internal/highleveltests
+	go test -v -race -tags enable_highlevel_tests ./internal/testhighlevel
 
 define DOCKERFILE_HIGHLEVEL_TEST
 FROM $(BASE_IMAGE)