[API] Forgejo API /api/forgejo/v1

(cherry picked from commit 20b56692693e054bb3c04b4ef12b29b0715b4530)
(cherry picked from commit 1574643a6a9634e5b92c033a4bfb69062a86bd05)

Update semantic version according to specification

(cherry picked from commit 22510f41306f9c133a7e99b61f9c38dabfd4b810)

Mise à jour de 'Makefile'

(cherry picked from commit c3d85d8409f1bb18a45659a167cf1ffee057f3b6)
(cherry picked from commit 5ea23098513c068444226af41faf9be9c4c998e6)
(cherry picked from commit 4f3970e6c46d0bec217f84c5a06d2523b6a6c104)

[API] [SEMVER] replace number with version

[API] [SEMVER] [v1.20] less is replaced by css

(cherry picked from commit 43a3a40825ec8257732139d704b46dabc8c77b4f)
(cherry picked from commit 669cea25bb202e5f8ee7bf16bd0dca4f43b04593)
(cherry picked from commit e25190d2b4bfdc2ca2be5163bafcfec19c8296d8)
(cherry picked from commit 5df876e19e7dec03803456e3b308b643c551b51e)
(cherry picked from commit fc94f6fae259e82189a89aa7e9307f394599f32b)
(cherry picked from commit 58c50c1fe408152790904c64fcdee9edfd6cafdc)

Makefile

@@ -102,7 +102,10 @@ ifeq ($(VERSION),main)
 	VERSION := main-nightly
 endif
 
-LDFLAGS := $(LDFLAGS) -X "main.MakeVersion=$(MAKE_VERSION)" -X "main.Version=$(GITEA_VERSION)" -X "main.Tags=$(TAGS)"
+# SemVer
+FORGEJO_VERSION := 3.0.0+0-gitea-1.19.0
+
+LDFLAGS := $(LDFLAGS) -X "main.MakeVersion=$(MAKE_VERSION)" -X "main.Version=$(GITEA_VERSION)" -X "main.Tags=$(TAGS)" -X "code.gitea.io/gitea/routers/api/forgejo/v1.ForgejoVersion=$(FORGEJO_VERSION)"
 
 LINUX_ARCHS ?= linux/amd64,linux/386,linux/arm-5,linux/arm-6,linux/arm64
 
@@ -154,6 +157,8 @@ ifdef DEPS_PLAYWRIGHT
 	PLAYWRIGHT_FLAGS += --with-deps
 endif
 
+FORGEJO_API_SPEC := public/forgejo/api.v1.yml
+
 SWAGGER_SPEC := templates/swagger/v1_json.tmpl
 SWAGGER_SPEC_S_TMPL := s|"basePath": *"/api/v1"|"basePath": "{{AppSubUrl \| JSEscape \| Safe}}/api/v1"|g
 SWAGGER_SPEC_S_JSON := s|"basePath": *"{{AppSubUrl \| JSEscape \| Safe}}/api/v1"|"basePath": "/api/v1"|g
@@ -214,6 +219,8 @@ help:
 	@echo " - generate-license                 update license files"
 	@echo " - generate-gitignore               update gitignore files"
 	@echo " - generate-manpage                 generate manpage"
+	@echo " - generate-forgejo-api             generate the forgejo API from spec"
+	@echo " - forgejo-api-validate             check if the forgejo API matches the specs"
 	@echo " - generate-swagger                 generate the swagger spec from code comments"
 	@echo " - swagger-validate                 check if the swagger spec is valid"
 	@echo " - golangci-lint                    run golangci-lint linter"
@@ -303,6 +310,27 @@ ifneq "$(TAGS)" "$(shell cat $(TAGS_EVIDENCE) 2>/dev/null)"
 TAGS_PREREQ := $(TAGS_EVIDENCE)
 endif
 
+OAPI_CODEGEN_PACKAGE ?= github.com/deepmap/oapi-codegen/cmd/oapi-codegen@v1.12.4
+KIN_OPENAPI_CODEGEN_PACKAGE ?= github.com/getkin/kin-openapi/cmd/validate@v0.114.0
+FORGEJO_API_SERVER = routers/api/forgejo/v1/generated.go
+
+.PHONY: generate-forgejo-api
+generate-forgejo-api: $(FORGEJO_API_SPEC)
+	$(GO) run $(OAPI_CODEGEN_PACKAGE) -package v1 -generate chi-server,types $< > $(FORGEJO_API_SERVER)
+
+.PHONY: forgejo-api-check
+forgejo-api-check: generate-forgejo-api
+	@diff=$$(git diff $(FORGEJO_API_SERVER) ; \
+	if [ -n "$$diff" ]; then \
+		echo "Please run 'make generate-forgejo-api' and commit the result:"; \
+		echo "$${diff}"; \
+		exit 1; \
+	fi
+
+.PHONY: forgejo-api-validate
+forgejo-api-validate:
+	$(GO) run $(KIN_OPENAPI_CODEGEN_PACKAGE) $(FORGEJO_API_SPEC)
+
 .PHONY: generate-swagger
 generate-swagger: $(SWAGGER_SPEC)
 
@@ -338,7 +366,7 @@ checks: checks-frontend checks-backend
 checks-frontend: lockfile-check svg-check
 
 .PHONY: checks-backend
-checks-backend: tidy-check swagger-check fmt-check misspell-check swagger-validate security-check
+checks-backend: tidy-check swagger-check fmt-check misspell-check forgejo-api-validate swagger-validate security-check
 
 .PHONY: lint
 lint: lint-frontend lint-backend

public/forgejo/api.v1.yml

@@ -0,0 +1,40 @@
+openapi: 3.0.0
+info:
+  title: Forgejo API
+  description: |-
+    Forgejo REST API
+
+  contact:
+    email: contact@forgejo.org
+  license:
+    name: MIT
+    url: https://codeberg.org/forgejo/forgejo/src/branch/forgejo/LICENSE
+  version: 1.0.0
+externalDocs:
+  description: Find out more about Forgejo
+  url: http://forgejo.org
+servers:
+  - url: /api/forgejo/v1
+paths:
+  /version:
+    get:
+      summary: API version
+      description: Semantic version of the Forgejo API
+      operationId: getVersion
+      responses:
+        '200':
+          description: successful operation
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Version'
+components:
+  schemas:
+    Version:
+      type: object
+      properties:
+        version:
+          type: string
+

routers/api/forgejo/v1/api.go

@@ -0,0 +1,18 @@
+// Copyright 2023 The Forgejo Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package v1
+
+import (
+	gocontext "context"
+
+	"code.gitea.io/gitea/modules/web"
+)
+
+func Routes(ctx gocontext.Context) *web.Route {
+	m := web.NewRoute()
+	forgejo := NewForgejo()
+	m.Get("", Root)
+	m.Get("/version", forgejo.GetVersion)
+	return m
+}

routers/api/forgejo/v1/forgejo.go

@@ -0,0 +1,24 @@
+// SPDX-License-Identifier: MIT
+
+package v1
+
+import (
+	"net/http"
+
+	"code.gitea.io/gitea/modules/json"
+)
+
+type Forgejo struct{}
+
+var _ ServerInterface = &Forgejo{}
+
+func NewForgejo() *Forgejo {
+	return &Forgejo{}
+}
+
+var ForgejoVersion = "development"
+
+func (f *Forgejo) GetVersion(w http.ResponseWriter, r *http.Request) {
+	w.WriteHeader(http.StatusOK)
+	_ = json.NewEncoder(w).Encode(Version{&ForgejoVersion})
+}

routers/api/forgejo/v1/generated.go

@@ -0,0 +1,167 @@
+// Package v1 provides primitives to interact with the openapi HTTP API.
+//
+// Code generated by github.com/deepmap/oapi-codegen version v1.12.4 DO NOT EDIT.
+package v1
+
+import (
+	"fmt"
+	"net/http"
+
+	"github.com/go-chi/chi/v5"
+)
+
+// Version defines model for Version.
+type Version struct {
+	Version *string `json:"version,omitempty"`
+}
+
+// ServerInterface represents all server handlers.
+type ServerInterface interface {
+	// API version
+	// (GET /version)
+	GetVersion(w http.ResponseWriter, r *http.Request)
+}
+
+// ServerInterfaceWrapper converts contexts to parameters.
+type ServerInterfaceWrapper struct {
+	Handler            ServerInterface
+	HandlerMiddlewares []MiddlewareFunc
+	ErrorHandlerFunc   func(w http.ResponseWriter, r *http.Request, err error)
+}
+
+type MiddlewareFunc func(http.Handler) http.Handler
+
+// GetVersion operation middleware
+func (siw *ServerInterfaceWrapper) GetVersion(w http.ResponseWriter, r *http.Request) {
+	ctx := r.Context()
+
+	var handler http.Handler = http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		siw.Handler.GetVersion(w, r)
+	})
+
+	for _, middleware := range siw.HandlerMiddlewares {
+		handler = middleware(handler)
+	}
+
+	handler.ServeHTTP(w, r.WithContext(ctx))
+}
+
+type UnescapedCookieParamError struct {
+	ParamName string
+	Err       error
+}
+
+func (e *UnescapedCookieParamError) Error() string {
+	return fmt.Sprintf("error unescaping cookie parameter '%s'", e.ParamName)
+}
+
+func (e *UnescapedCookieParamError) Unwrap() error {
+	return e.Err
+}
+
+type UnmarshallingParamError struct {
+	ParamName string
+	Err       error
+}
+
+func (e *UnmarshallingParamError) Error() string {
+	return fmt.Sprintf("Error unmarshalling parameter %s as JSON: %s", e.ParamName, e.Err.Error())
+}
+
+func (e *UnmarshallingParamError) Unwrap() error {
+	return e.Err
+}
+
+type RequiredParamError struct {
+	ParamName string
+}
+
+func (e *RequiredParamError) Error() string {
+	return fmt.Sprintf("Query argument %s is required, but not found", e.ParamName)
+}
+
+type RequiredHeaderError struct {
+	ParamName string
+	Err       error
+}
+
+func (e *RequiredHeaderError) Error() string {
+	return fmt.Sprintf("Header parameter %s is required, but not found", e.ParamName)
+}
+
+func (e *RequiredHeaderError) Unwrap() error {
+	return e.Err
+}
+
+type InvalidParamFormatError struct {
+	ParamName string
+	Err       error
+}
+
+func (e *InvalidParamFormatError) Error() string {
+	return fmt.Sprintf("Invalid format for parameter %s: %s", e.ParamName, e.Err.Error())
+}
+
+func (e *InvalidParamFormatError) Unwrap() error {
+	return e.Err
+}
+
+type TooManyValuesForParamError struct {
+	ParamName string
+	Count     int
+}
+
+func (e *TooManyValuesForParamError) Error() string {
+	return fmt.Sprintf("Expected one value for %s, got %d", e.ParamName, e.Count)
+}
+
+// Handler creates http.Handler with routing matching OpenAPI spec.
+func Handler(si ServerInterface) http.Handler {
+	return HandlerWithOptions(si, ChiServerOptions{})
+}
+
+type ChiServerOptions struct {
+	BaseURL          string
+	BaseRouter       chi.Router
+	Middlewares      []MiddlewareFunc
+	ErrorHandlerFunc func(w http.ResponseWriter, r *http.Request, err error)
+}
+
+// HandlerFromMux creates http.Handler with routing matching OpenAPI spec based on the provided mux.
+func HandlerFromMux(si ServerInterface, r chi.Router) http.Handler {
+	return HandlerWithOptions(si, ChiServerOptions{
+		BaseRouter: r,
+	})
+}
+
+func HandlerFromMuxWithBaseURL(si ServerInterface, r chi.Router, baseURL string) http.Handler {
+	return HandlerWithOptions(si, ChiServerOptions{
+		BaseURL:    baseURL,
+		BaseRouter: r,
+	})
+}
+
+// HandlerWithOptions creates http.Handler with additional options
+func HandlerWithOptions(si ServerInterface, options ChiServerOptions) http.Handler {
+	r := options.BaseRouter
+
+	if r == nil {
+		r = chi.NewRouter()
+	}
+	if options.ErrorHandlerFunc == nil {
+		options.ErrorHandlerFunc = func(w http.ResponseWriter, r *http.Request, err error) {
+			http.Error(w, err.Error(), http.StatusBadRequest)
+		}
+	}
+	wrapper := ServerInterfaceWrapper{
+		Handler:            si,
+		HandlerMiddlewares: options.Middlewares,
+		ErrorHandlerFunc:   options.ErrorHandlerFunc,
+	}
+
+	r.Group(func(r chi.Router) {
+		r.Get(options.BaseURL+"/version", wrapper.GetVersion)
+	})
+
+	return r
+}

routers/api/forgejo/v1/root.go

@@ -0,0 +1,14 @@
+// Copyright The Forgejo Authors.
+// SPDX-License-Identifier: MIT
+
+package v1
+
+import (
+	"net/http"
+)
+
+func Root(w http.ResponseWriter, r *http.Request) {
+	// https://www.rfc-editor.org/rfc/rfc8631
+	w.Header().Set("Link", "</assets/forgejo/api.v1.yml>; rel=\"service-desc\"")
+	w.WriteHeader(http.StatusNoContent)
+}

routers/init.go

@@ -31,6 +31,7 @@ import (
 	"code.gitea.io/gitea/modules/util"
 	"code.gitea.io/gitea/modules/web"
 	actions_router "code.gitea.io/gitea/routers/api/actions"
+	forgejo "code.gitea.io/gitea/routers/api/forgejo/v1"
 	packages_router "code.gitea.io/gitea/routers/api/packages"
 	apiv1 "code.gitea.io/gitea/routers/api/v1"
 	"code.gitea.io/gitea/routers/common"
@@ -190,6 +191,7 @@ func NormalRoutes(ctx context.Context) *web.Route {
 
 	r.Mount("/", web_routers.Routes(ctx))
 	r.Mount("/api/v1", apiv1.Routes(ctx))
+	r.Mount("/api/forgejo/v1", forgejo.Routes(ctx))
 	r.Mount("/api/internal", private.Routes())
 
 	if setting.Packages.Enabled {

routers/web/misc/swagger-forgejo.go

@@ -0,0 +1,19 @@
+// Copyright 2017 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package misc
+
+import (
+	"net/http"
+
+	"code.gitea.io/gitea/modules/base"
+	"code.gitea.io/gitea/modules/context"
+)
+
+// tplSwagger swagger page template
+const tplForgejoSwagger base.TplName = "swagger/forgejo-ui"
+
+func SwaggerForgejo(ctx *context.Context) {
+	ctx.Data["APIVersion"] = "v1"
+	ctx.HTML(http.StatusOK, tplForgejoSwagger)
+}

routers/web/web.go

@@ -212,6 +212,7 @@ func Routes(ctx gocontext.Context) *web.Route {
 	if setting.API.EnableSwagger {
 		// Note: The route moved from apiroutes because it's in fact want to render a web page
 		routes.Get("/api/swagger", append(common, misc.Swagger)...) // Render V1 by default
+		routes.Get("/api/forgejo/swagger", append(common, misc.SwaggerForgejo)...)
 	}
 
 	// TODO: These really seem like things that could be folded into Contexter or as helper functions

templates/swagger/forgejo-ui.tmpl

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html lang="en">
+	<head>
+		<meta charset="UTF-8">
+		<title>Forgejo API</title>
+		<link href="{{AssetUrlPrefix}}/css/swagger.css?v={{AssetVersion}}" rel="stylesheet">
+	</head>
+	<body>
+		<a class="swagger-back-link" href="{{AppUrl}}">{{svg "octicon-reply"}}{{.locale.Tr "return_to_gitea"}}</a>
+		<div id="swagger-ui" data-source="{{AssetUrlPrefix}}/forgejo/api.{{.APIVersion}}.yml"></div>
+		<script src="{{AssetUrlPrefix}}/js/forgejoswagger.js?v={{AssetVersion}}"></script>
+	</body>
+</html>

tests/integration/api_forgejo_root_test.go

@@ -0,0 +1,21 @@
+// Copyright The Forgejo Authors.
+// SPDX-License-Identifier: MIT
+
+package integration
+
+import (
+	"net/http"
+	"testing"
+
+	"code.gitea.io/gitea/tests"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestAPIForgejoRoot(t *testing.T) {
+	defer tests.PrepareTestEnv(t)()
+
+	req := NewRequest(t, "GET", "/api/forgejo/v1")
+	resp := MakeRequest(t, req, http.StatusNoContent)
+	assert.Contains(t, resp.Header().Get("Link"), "/assets/forgejo/api.v1.yml")
+}

tests/integration/api_forgejo_version_test.go

@@ -0,0 +1,25 @@
+// Copyright The Forgejo Authors.
+// SPDX-License-Identifier: MIT
+
+package integration
+
+import (
+	"net/http"
+	"testing"
+
+	"code.gitea.io/gitea/routers/api/forgejo/v1"
+	"code.gitea.io/gitea/tests"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestAPIForgejoVersion(t *testing.T) {
+	defer tests.PrepareTestEnv(t)()
+
+	req := NewRequest(t, "GET", "/api/forgejo/v1/version")
+	resp := MakeRequest(t, req, http.StatusOK)
+
+	var version v1.Version
+	DecodeJSON(t, resp, &version)
+	assert.Equal(t, "development", *version.Version)
+}

web_src/js/standalone/forgejo-swagger.js

@@ -0,0 +1,22 @@
+import SwaggerUI from 'swagger-ui-dist/swagger-ui-es-bundle.js';
+import 'swagger-ui-dist/swagger-ui.css';
+
+window.addEventListener('load', async () => {
+  const url = document.getElementById('swagger-ui').getAttribute('data-source');
+
+  const ui = SwaggerUI({
+    url: url,
+    dom_id: '#swagger-ui',
+    deepLinking: true,
+    docExpansion: 'none',
+    defaultModelRendering: 'model', // don't show examples by default, because they may be incomplete
+    presets: [
+      SwaggerUI.presets.apis
+    ],
+    plugins: [
+      SwaggerUI.plugins.DownloadUrl
+    ]
+  });
+
+  window.ui = ui;
+});

webpack.config.js

@@ -60,7 +60,11 @@ export default {
       fileURLToPath(new URL('web_src/css/index.css', import.meta.url)),
     ],
     webcomponents: [
-      fileURLToPath(new URL('web_src/js/webcomponents/GiteaOriginUrl.js', import.meta.url)),
+	fileURLToPath(new URL('web_src/js/webcomponents/GiteaOriginUrl.js', import.meta.url)),
+    ],
+    forgejoswagger: [ // Forgejo swagger is OpenAPI 3.0.0 and has specific parameters
+	fileURLToPath(new URL('web_src/js/standalone/forgejo-swagger.js', import.meta.url)),
+	fileURLToPath(new URL('web_src/css/standalone/swagger.css', import.meta.url)),
     ],
     swagger: [
       fileURLToPath(new URL('web_src/js/standalone/swagger.js', import.meta.url)),