From 972ffbf3323b8cf241b76fdf4111b8d04e579270 Mon Sep 17 00:00:00 2001 From: Alessandro Ros Date: Sun, 4 Aug 2024 13:12:30 +0200 Subject: [PATCH] improve API docs linter (#3608) --- .github/workflows/code_lint.yml | 6 +- .github/workflows/release.yml | 2 +- Makefile | 3 +- internal/testapidocs/apidocs_test.go | 154 ++++++++++++++++++ .../build_images_test.go | 2 +- .../hls_manager_test.go | 2 +- .../images/ffmpeg/Dockerfile | 0 .../images/ffmpeg/emptyvideo.mkv | Bin .../images/ffmpeg/emptyvideoaudio.mkv | Bin .../images/ffmpeg/start.sh | 0 .../images/gstreamer/Dockerfile | 0 .../images/gstreamer/emptyvideo.mkv | Bin .../images/gstreamer/exitafterframe.c | 0 .../images/gstreamer/start.sh | 0 .../images/vlc/Dockerfile | 0 .../images/vlc/start.sh | 0 .../rtsp_server_test.go | 2 +- .../tests_test.go | 2 +- scripts/apidocs.mk | 13 +- scripts/lint.mk | 19 ++- scripts/test-highlevel.mk | 2 +- 21 files changed, 182 insertions(+), 25 deletions(-) create mode 100644 internal/testapidocs/apidocs_test.go rename internal/{highleveltests => testhighlevel}/build_images_test.go (96%) rename internal/{highleveltests => testhighlevel}/hls_manager_test.go (98%) rename internal/{highleveltests => testhighlevel}/images/ffmpeg/Dockerfile (100%) rename internal/{highleveltests => testhighlevel}/images/ffmpeg/emptyvideo.mkv (100%) rename internal/{highleveltests => testhighlevel}/images/ffmpeg/emptyvideoaudio.mkv (100%) rename internal/{highleveltests => testhighlevel}/images/ffmpeg/start.sh (100%) rename internal/{highleveltests => testhighlevel}/images/gstreamer/Dockerfile (100%) rename internal/{highleveltests => testhighlevel}/images/gstreamer/emptyvideo.mkv (100%) rename internal/{highleveltests => testhighlevel}/images/gstreamer/exitafterframe.c (100%) rename internal/{highleveltests => testhighlevel}/images/gstreamer/start.sh (100%) rename internal/{highleveltests => testhighlevel}/images/vlc/Dockerfile (100%) rename internal/{highleveltests => testhighlevel}/images/vlc/start.sh (100%) rename internal/{highleveltests => testhighlevel}/rtsp_server_test.go (99%) rename internal/{highleveltests => testhighlevel}/tests_test.go (98%) diff --git a/.github/workflows/code_lint.yml b/.github/workflows/code_lint.yml index d9cafd22..0c775154 100644 --- a/.github/workflows/code_lint.yml +++ b/.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 diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 99639ceb..b375609c 100644 --- a/.github/workflows/release.yml +++ b/.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 diff --git a/Makefile b/Makefile index 2bd05b85..5414070d 100644 --- a/Makefile +++ b/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)" diff --git a/internal/testapidocs/apidocs_test.go b/internal/testapidocs/apidocs_test.go new file mode 100644 index 00000000..63c38c4d --- /dev/null +++ b/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) + }) + } +} diff --git a/internal/highleveltests/build_images_test.go b/internal/testhighlevel/build_images_test.go similarity index 96% rename from internal/highleveltests/build_images_test.go rename to internal/testhighlevel/build_images_test.go index 1f164f8a..7d24e4b1 100644 --- a/internal/highleveltests/build_images_test.go +++ b/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" diff --git a/internal/highleveltests/hls_manager_test.go b/internal/testhighlevel/hls_manager_test.go similarity index 98% rename from internal/highleveltests/hls_manager_test.go rename to internal/testhighlevel/hls_manager_test.go index 424c71ca..b0cc8c19 100644 --- a/internal/highleveltests/hls_manager_test.go +++ b/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" diff --git a/internal/highleveltests/images/ffmpeg/Dockerfile b/internal/testhighlevel/images/ffmpeg/Dockerfile similarity index 100% rename from internal/highleveltests/images/ffmpeg/Dockerfile rename to internal/testhighlevel/images/ffmpeg/Dockerfile diff --git a/internal/highleveltests/images/ffmpeg/emptyvideo.mkv b/internal/testhighlevel/images/ffmpeg/emptyvideo.mkv similarity index 100% rename from internal/highleveltests/images/ffmpeg/emptyvideo.mkv rename to internal/testhighlevel/images/ffmpeg/emptyvideo.mkv diff --git a/internal/highleveltests/images/ffmpeg/emptyvideoaudio.mkv b/internal/testhighlevel/images/ffmpeg/emptyvideoaudio.mkv similarity index 100% rename from internal/highleveltests/images/ffmpeg/emptyvideoaudio.mkv rename to internal/testhighlevel/images/ffmpeg/emptyvideoaudio.mkv diff --git a/internal/highleveltests/images/ffmpeg/start.sh b/internal/testhighlevel/images/ffmpeg/start.sh similarity index 100% rename from internal/highleveltests/images/ffmpeg/start.sh rename to internal/testhighlevel/images/ffmpeg/start.sh diff --git a/internal/highleveltests/images/gstreamer/Dockerfile b/internal/testhighlevel/images/gstreamer/Dockerfile similarity index 100% rename from internal/highleveltests/images/gstreamer/Dockerfile rename to internal/testhighlevel/images/gstreamer/Dockerfile diff --git a/internal/highleveltests/images/gstreamer/emptyvideo.mkv b/internal/testhighlevel/images/gstreamer/emptyvideo.mkv similarity index 100% rename from internal/highleveltests/images/gstreamer/emptyvideo.mkv rename to internal/testhighlevel/images/gstreamer/emptyvideo.mkv diff --git a/internal/highleveltests/images/gstreamer/exitafterframe.c b/internal/testhighlevel/images/gstreamer/exitafterframe.c similarity index 100% rename from internal/highleveltests/images/gstreamer/exitafterframe.c rename to internal/testhighlevel/images/gstreamer/exitafterframe.c diff --git a/internal/highleveltests/images/gstreamer/start.sh b/internal/testhighlevel/images/gstreamer/start.sh similarity index 100% rename from internal/highleveltests/images/gstreamer/start.sh rename to internal/testhighlevel/images/gstreamer/start.sh diff --git a/internal/highleveltests/images/vlc/Dockerfile b/internal/testhighlevel/images/vlc/Dockerfile similarity index 100% rename from internal/highleveltests/images/vlc/Dockerfile rename to internal/testhighlevel/images/vlc/Dockerfile diff --git a/internal/highleveltests/images/vlc/start.sh b/internal/testhighlevel/images/vlc/start.sh similarity index 100% rename from internal/highleveltests/images/vlc/start.sh rename to internal/testhighlevel/images/vlc/start.sh diff --git a/internal/highleveltests/rtsp_server_test.go b/internal/testhighlevel/rtsp_server_test.go similarity index 99% rename from internal/highleveltests/rtsp_server_test.go rename to internal/testhighlevel/rtsp_server_test.go index 4d7e75af..48bd9f7b 100644 --- a/internal/highleveltests/rtsp_server_test.go +++ b/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" diff --git a/internal/highleveltests/tests_test.go b/internal/testhighlevel/tests_test.go similarity index 98% rename from internal/highleveltests/tests_test.go rename to internal/testhighlevel/tests_test.go index e22ebc39..b72d88d4 100644 --- a/internal/highleveltests/tests_test.go +++ b/internal/testhighlevel/tests_test.go @@ -1,7 +1,7 @@ //go:build enable_highlevel_tests // +build enable_highlevel_tests -package highleveltests +package testhighlevel import ( "os" diff --git a/scripts/apidocs.mk b/scripts/apidocs.mk index 34c6510c..e06a006c 100644 --- a/scripts/apidocs.mk +++ b/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" diff --git a/scripts/lint.mk b/scripts/lint.mk index 5245ac8c..f42ec326 100644 --- a/scripts/lint.mk +++ b/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 diff --git a/scripts/test-highlevel.mk b/scripts/test-highlevel.mk index 60652213..173092a0 100644 --- a/scripts/test-highlevel.mk +++ b/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)