From 0c51595eedbb68643af73314ae1ab43eb5c95715 Mon Sep 17 00:00:00 2001 From: delvh Date: Tue, 20 Sep 2022 00:48:48 +0200 Subject: [PATCH] Clarify that `ENABLE_SWAGGER` only influences the API docs, not the routes (#21215) Previously, the docs seemed to suggest that you can disable the API completely by setting `ENABLE_SWAGGER=false`. This is not the case. --- custom/conf/app.example.ini | 4 ++-- docs/content/doc/advanced/config-cheat-sheet.en-us.md | 4 ++-- docs/content/doc/advanced/config-cheat-sheet.zh-cn.md | 2 +- docs/content/doc/help/faq.en-us.md | 10 +++++----- 4 files changed, 10 insertions(+), 10 deletions(-) diff --git a/custom/conf/app.example.ini b/custom/conf/app.example.ini index 6e1eca7a62..0e0822d4c5 100644 --- a/custom/conf/app.example.ini +++ b/custom/conf/app.example.ini @@ -2153,7 +2153,7 @@ ROUTER = console ;[api] ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; -;; Enables Swagger. True or false; default is true. +;; Enables the API documentation endpoints (/api/swagger, /api/v1/swagger, …). True or false. ;ENABLE_SWAGGER = true ;; Max number of items in a page ;MAX_RESPONSE_ITEMS = 50 @@ -2161,7 +2161,7 @@ ROUTER = console ;DEFAULT_PAGING_NUM = 30 ;; Default and maximum number of items per page for git trees api ;DEFAULT_GIT_TREES_PER_PAGE = 1000 -;; Default size of a blob returned by the blobs API (default is 10MiB) +;; Default max size of a blob returned by the blobs API (default is 10MiB) ;DEFAULT_MAX_BLOB_SIZE = 10485760 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; diff --git a/docs/content/doc/advanced/config-cheat-sheet.en-us.md b/docs/content/doc/advanced/config-cheat-sheet.en-us.md index 459e42ac24..f39c501cbc 100644 --- a/docs/content/doc/advanced/config-cheat-sheet.en-us.md +++ b/docs/content/doc/advanced/config-cheat-sheet.en-us.md @@ -1015,11 +1015,11 @@ Default templates for project boards: ## API (`api`) -- `ENABLE_SWAGGER`: **true**: Enables /api/swagger, /api/v1/swagger etc. endpoints. True or false; default is true. +- `ENABLE_SWAGGER`: **true**: Enables the API documentation endpoints (`/api/swagger`, `/api/v1/swagger`, …). True or false. - `MAX_RESPONSE_ITEMS`: **50**: Max number of items in a page. - `DEFAULT_PAGING_NUM`: **30**: Default paging number of API. - `DEFAULT_GIT_TREES_PER_PAGE`: **1000**: Default and maximum number of items per page for Git trees API. -- `DEFAULT_MAX_BLOB_SIZE`: **10485760**: Default max size of a blob that can be return by the blobs API. +- `DEFAULT_MAX_BLOB_SIZE`: **10485760** (10MiB): Default max size of a blob that can be returned by the blobs API. ## OAuth2 (`oauth2`) diff --git a/docs/content/doc/advanced/config-cheat-sheet.zh-cn.md b/docs/content/doc/advanced/config-cheat-sheet.zh-cn.md index 34de3c0324..576007f75b 100644 --- a/docs/content/doc/advanced/config-cheat-sheet.zh-cn.md +++ b/docs/content/doc/advanced/config-cheat-sheet.zh-cn.md @@ -299,7 +299,7 @@ test01.xls: application/vnd.ms-excel; charset=binary ## API (`api`) -- `ENABLE_SWAGGER`: **true**: 是否启用swagger路由 /api/swagger, /api/v1/swagger etc. endpoints. True 或 false; 默认是 true. +- `ENABLE_SWAGGER`: **true**: 是否启用swagger路由 /api/swagger, /api/v1/swagger etc. endpoints. True 或 false. - `MAX_RESPONSE_ITEMS`: **50**: 一个页面最大的项目数。 - `DEFAULT_PAGING_NUM`: **30**: API中默认分页条数。 - `DEFAULT_GIT_TREES_PER_PAGE`: **1000**: GIT TREES API每页的默认最大项数. diff --git a/docs/content/doc/help/faq.en-us.md b/docs/content/doc/help/faq.en-us.md index 970a6866a6..f71cd734a5 100644 --- a/docs/content/doc/help/faq.en-us.md +++ b/docs/content/doc/help/faq.en-us.md @@ -126,13 +126,13 @@ A "login prohibited" user is a user that is not allowed to log in to Gitea anymo ## What is Swagger? -[Swagger](https://swagger.io/) is what Gitea uses for its API. +[Swagger](https://swagger.io/) is what Gitea uses for its API documentation. -All Gitea instances have the built-in API, though it can be disabled by setting `ENABLE_SWAGGER` to `false` in the `api` section of your `app.ini` +All Gitea instances have the built-in API and there is no way to disable it completely. +You can, however, disable showing its documentation by setting `ENABLE_SWAGGER` to `false` in the `api` section of your `app.ini`. +For more information, refer to Gitea's [API docs]({{< relref "doc/developers/api-usage.en-us.md" >}}). -For more information, refer to Gitea's [API docs]({{< relref "doc/developers/api-usage.en-us.md" >}}) - -[Swagger Example](https://try.gitea.io/api/swagger) +You can see the latest API (for example) on . ## Adjusting your server for public/private use