Skip to content

Commit 32d4545

Browse files
apolukhinapolukhin
committed
feat docs: use schemas in core for docs in more cases
Tests: протестировано в CI, проверено локально что все поля отображаются и форматируются приятно для глаза (или хотя бы как было раньше) commit_hash:03e3c67de1f3df7674ae80a2d2307c169c7f4019
1 parent 66190c6 commit 32d4545

File tree

11 files changed

+96
-120
lines changed

11 files changed

+96
-120
lines changed

‎core/include/userver/server/handlers/auth/digest/auth_checker_settings_component.hpp‎

Lines changed: 6 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -18,18 +18,13 @@ namespace server::handlers::auth::digest {
1818

1919
// clang-format off
2020

21-
/// @brief Component that loads digest auth configuration settings from a
22-
/// static_config.yaml
23-
/// ## Static options:
21+
/// @brief Component that loads digest auth configuration settings from a static_config.yaml
2422
///
25-
/// Name | Description | Default value
26-
/// ---------- | ---------------------------------------------- | -------------
27-
/// algorithm | algorithm for hashing nonce   | sha256
28-
/// domains | list of URIs, that define the protection space | /
29-
/// qops | list of supported qop-options. Use `auth` for authentication and `auth-in` for authentication with integrity protection | auth
30-
/// is-proxy | indicates that the server is a proxy server. If set, the Proxy prefix is inserted into the header | false
31-
/// is-session | activate session algorithm (md5-sess, sha256-sess or sha512-sess) | false
32-
/// nonce-ttl | ttl for nonce | 10s
23+
/// ## Static options of server::handlers::auth::digest::AuthCheckerSettingsComponent :
24+
/// @include{doc} scripts/docs/en/components_schema/core/src/server/handlers/auth/digest/auth_checker_settings_component.md
25+
///
26+
/// Options inherited from @ref components::ComponentBase :
27+
/// @include{doc} scripts/docs/en/components_schema/core/src/components/impl/component_base.md
3328

3429
// clang-format on
3530

‎core/include/userver/server/handlers/auth/digest/nonce_cache_settings_component.hpp‎

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -26,12 +26,15 @@ struct NonceCacheSettings {
2626
// clang-format off
2727

2828
/// @brief Component that loads nonce cache settings from a static_config.yaml
29-
/// ## Static options:
3029
///
31-
/// Name | Description | Default value
32-
/// ------ | --------------------------------------| -------------
33-
/// size | max amount of items to store in cache | -
34-
/// ways | number of ways for associative cache | -
30+
/// ## Static options of server::handlers::auth::digest::NonceCacheSettingsComponent :
31+
/// @include{doc} scripts/docs/en/components_schema/core/src/server/handlers/auth/digest/nonce_cache_settings_component.md
32+
///
33+
/// Options inherited from @ref server::handlers::auth::digest::AuthCheckerSettingsComponent :
34+
/// @include{doc} scripts/docs/en/components_schema/core/src/server/handlers/auth/digest/auth_checker_settings_component.md
35+
///
36+
/// Options inherited from @ref components::ComponentBase :
37+
/// @include{doc} scripts/docs/en/components_schema/core/src/components/impl/component_base.md
3538

3639
// clang-format on
3740

‎core/include/userver/server/handlers/handler_base.hpp‎

Lines changed: 6 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -13,39 +13,15 @@ USERVER_NAMESPACE_BEGIN
1313

1414
namespace server::handlers {
1515

16-
// clang-format off
17-
1816
/// @brief Base class for the request handlers.
1917
///
20-
/// Each handler has an associated path and invoked only for the requests for
21-
/// that path.
18+
/// Each handler has an associated path and invoked only for the requests for that path.
2219
///
23-
/// ## Static options:
24-
/// Name | Description | Default value
25-
/// ---- | ----------- | -------------
26-
/// path | if a request matches this path wildcard then process it by handler | -
27-
/// as_fallback | set to "implicit-http-options" and do not specify a path if this handler processes the OPTIONS requests for paths that do not process OPTIONS method | -
28-
/// task_processor | a task processor to execute the requests | the 'default_task_processor' value from components::ManagerControllerComponent
29-
/// method | comma-separated list of allowed HTTP methods. HEAD method is implicitly enabled if GET method is enabled | -
30-
/// max_request_size | max size of the whole request | 1024 * 1024
31-
/// max_headers_size | max request headers size | 65536
32-
/// parse_args_from_body | optional field to parse request according to x-www-form-urlencoded rules and make parameters accessible as query parameters | false
33-
/// auth | server::handlers::auth::HandlerAuthConfig authorization config | -
34-
/// url_trailing_slash | 'both' to treat URLs with and without a trailing slash as equal, 'strict-match' otherwise | 'both'
35-
/// max_requests_in_flight | integer to limit max pending requests to this handler | `<no limit>`
36-
/// request_body_size_log_limit | trim request to this size before logging | 512
37-
/// request_headers_size_log_limit | limit on the total length of logged headers | 512
38-
/// response_data_size_log_limit | trim responses to this size before logging | 512
39-
/// max_requests_per_second | integer to limit RPS to this handler | `<no limit>`
40-
/// decompress_request | allow decompression of the requests | true
41-
/// throttling_enabled | allow throttling of the requests by components::Server , for more info see its `max_response_size_in_flight` and `requests_queue_size_threshold` options | true
42-
/// set-response-server-hostname | set to true to add the `X-YaTaxi-Server-Hostname` header with instance name, set to false to not add the header | `<takes the value from components::Server config>`
43-
/// monitor-handler | Overrides the in-code `is_monitor` flag that makes the handler run either on `server.listener` or on `server.listener-monitor` | --
44-
/// set_tracing_headers | whether to set http tracing headers (X-YaTraceId, X-YaSpanId, X-RequestId) | true
45-
/// deadline_propagation_enabled | when `false`, disables HTTP handler @ref scripts/docs/en/userver/deadline_propagation.md "deadline propagation" | true
46-
/// deadline_expired_status_code | the HTTP status code to return if the request @ref scripts/docs/en/userver/deadline_propagation.md "deadline expires" | 498
47-
48-
// clang-format on
20+
/// ## Static options of server::handlers::HandlerBase :
21+
/// @include{doc} scripts/docs/en/components_schema/core/src/server/handlers/handler_base.md
22+
///
23+
/// Options inherited from @ref components::ComponentBase :
24+
/// @include{doc} scripts/docs/en/components_schema/core/src/components/impl/component_base.md
4925
class HandlerBase : public components::ComponentBase {
5026
public:
5127
HandlerBase(

‎core/include/userver/server/handlers/http_handler_base.hpp‎

Lines changed: 8 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -38,30 +38,23 @@ class HttpRequestStatistics;
3838
class HttpHandlerMethodStatistics;
3939
class HttpHandlerStatisticsScope;
4040

41-
// clang-format off
42-
4341
/// @ingroup userver_components userver_http_handlers userver_base_classes
4442
///
45-
/// @brief Base class for all the
46-
/// \ref userver_http_handlers "Userver HTTP Handlers".
43+
/// @brief Base class for all the @ref userver_http_handlers "Userver HTTP Handlers".
44+
///
45+
/// ## Static options of server::handlers::HttpHandlerBase :
46+
/// @include{doc} scripts/docs/en/components_schema/core/src/server/handlers/http_handler_base.md
4747
///
48-
/// ## Static options:
49-
/// Inherits all the options from server::handlers::HandlerBase and adds the
50-
/// following ones:
48+
/// Options inherited from @ref server::handlers::HandlerBase :
49+
/// @include{doc} scripts/docs/en/components_schema/core/src/server/handlers/handler_base.md
5150
///
52-
/// Name | Description | Default value
53-
/// ---- | ----------- | -------------
54-
/// log-level | overrides log level for this handle | `<no override>`
55-
/// status-codes-log-level | map of "status": log_level items to override span log level for specific status codes | {}
56-
/// middlewares.pipeline-builder | name of a component to build a middleware pipeline for this particular handler | default-handler-middleware-pipeline-builder
51+
/// Options inherited from @ref components::ComponentBase :
52+
/// @include{doc} scripts/docs/en/components_schema/core/src/components/impl/component_base.md
5753
///
5854
/// ## Example usage:
5955
///
6056
/// @include samples/hello_service/src/hello_handler.hpp
6157
/// @include samples/hello_service/src/hello_handler.cpp
62-
63-
// clang-format on
64-
6558
class HttpHandlerBase : public HandlerBase {
6659
public:
6760
HttpHandlerBase(

‎core/include/userver/server/handlers/http_handler_static.hpp‎

Lines changed: 10 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -12,8 +12,6 @@ USERVER_NAMESPACE_BEGIN
1212

1313
namespace server::handlers {
1414

15-
// clang-format off
16-
1715
/// @ingroup userver_components userver_http_handlers
1816
///
1917
/// @brief Handler that returns HTTP 200 if file exist and returns file data with mapped content/type.
@@ -32,23 +30,21 @@ namespace server::handlers {
3230
///
3331
/// \ref userver_http_handlers "Userver HTTP Handlers".
3432
///
35-
/// ## Static options:
36-
/// Inherits all the options from server::handlers::HttpHandlerBase and adds the
37-
/// following ones:
33+
/// ## Static options of server::handlers::HttpHandlerStatic :
34+
/// @include{doc} scripts/docs/en/components_schema/core/src/server/handlers/http_handler_static.md
35+
///
36+
/// Options inherited from @ref server::handlers::HttpHandlerBase :
37+
/// @include{doc} scripts/docs/en/components_schema/core/src/server/handlers/http_handler_base.md
38+
///
39+
/// Options inherited from @ref server::handlers::HandlerBase :
40+
/// @include{doc} scripts/docs/en/components_schema/core/src/server/handlers/handler_base.md
3841
///
39-
/// Name | Description | Default value
40-
/// ------------------ | ----------------------------------------------------------------------------------------- | -------------
41-
/// fs-cache-component | Name of the components::FsCache component | fs-cache-component
42-
/// expires | Cache age in seconds | 600
43-
/// directory-file | File to return for directory requests. File name (not path) search in requested directory | "index.html"
44-
/// not-found-file | File to return for missing files | "/404.html"
42+
/// Options inherited from @ref components::ComponentBase :
43+
/// @include{doc} scripts/docs/en/components_schema/core/src/components/impl/component_base.md
4544
///
4645
/// ## Example usage:
4746
///
4847
/// @snippet samples/static_service/main.cpp Static service sample - main
49-
50-
// clang-format on
51-
5248
class HttpHandlerStatic final : public HttpHandlerBase {
5349
public:
5450
/// @ingroup userver_component_names

‎core/include/userver/server/handlers/implicit_options.hpp‎

Lines changed: 10 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,6 @@ using AuthCheckerBasePtr = std::shared_ptr<AuthCheckerBase>;
2323

2424
namespace server::handlers {
2525

26-
// clang-format off
2726
/// @ingroup userver_components userver_http_handlers
2827
///
2928
/// @brief A "magical" handler that will respond to OPTIONS HTTP method for any
@@ -48,24 +47,24 @@ namespace server::handlers {
4847
/// * `OK` if the check succeeds
4948
/// * an unspecified error message if the check fails
5049
///
51-
/// ## Static options
50+
/// ## Static options of server::handlers::ImplicitOptions :
51+
/// @include{doc} scripts/docs/en/components_schema/core/src/server/handlers/implicit_options.md
5252
///
53-
/// The component has no service configuration except the
54-
/// @ref userver_http_handlers "common handler options".
55-
/// and adds the following ones:
53+
/// Options inherited from @ref server::handlers::HttpHandlerBase :
54+
/// @include{doc} scripts/docs/en/components_schema/core/src/server/handlers/http_handler_base.md
5655
///
57-
/// Name | Description | Default value
58-
/// ---- | ----------- | -------------
59-
/// auth | server::handlers::auth::HandlerAuthConfig authorization config | auth checker testing is disabled
56+
/// Options inherited from @ref server::handlers::HandlerBase :
57+
/// @include{doc} scripts/docs/en/components_schema/core/src/server/handlers/handler_base.md
58+
///
59+
/// Options inherited from @ref components::ComponentBase :
60+
/// @include{doc} scripts/docs/en/components_schema/core/src/components/impl/component_base.md
6061
///
6162
/// ## Static configuration example:
6263
///
6364
/// @snippet components/common_server_component_list_test.cpp Sample handler implicit http options component config
6465
///
6566
/// ## Scheme
66-
/// Provide an optional query parameter `body` to get the bodies of all the
67-
/// in-flight requests.
68-
// clang-format on
67+
/// Provide an optional query parameter `body` to get the bodies of all the in-flight requests.
6968
class ImplicitOptions /*non-final*/ : public HttpHandlerBase {
7069
public:
7170
/// @ingroup userver_component_names

‎core/include/userver/server/handlers/ping.hpp‎

Lines changed: 18 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -18,8 +18,17 @@ namespace server::handlers {
1818
/// Uses components::State::IsAnyComponentInFatalState() to detect
1919
/// fatal state (can not process requests).
2020
///
21-
/// ## Static options:
22-
/// Inherits all the options from server::handlers::HttpHandlerBase
21+
/// ## Static options of server::handlers::PingBase:
22+
///
23+
/// Options inherited from @ref server::handlers::HttpHandlerBase :
24+
/// @include{doc} scripts/docs/en/components_schema/core/src/server/handlers/http_handler_base.md
25+
///
26+
/// Options inherited from @ref server::handlers::HandlerBase :
27+
/// @include{doc} scripts/docs/en/components_schema/core/src/server/handlers/handler_base.md
28+
///
29+
/// Options inherited from @ref components::ComponentBase :
30+
/// @include{doc} scripts/docs/en/components_schema/core/src/components/impl/component_base.md
31+
///
2332
/// @ref userver_http_handlers
2433
class PingBase : public HttpHandlerBase {
2534
public:
@@ -35,14 +44,14 @@ class PingBase : public HttpHandlerBase {
3544
///
3645
/// @brief Ping handler implementation with warmup
3746
///
38-
/// ## Static options:
39-
/// Inherits all the options from server::handlers::PingBase
40-
/// @ref userver_http_handlers
41-
/// and adds the following ones:
47+
/// ## Static options of server::handlers::Ping:
48+
/// @include{doc} scripts/docs/en/components_schema/ccore/src/server/handlers/ping.md
49+
///
50+
/// Options inherited from @ref server::handlers::HandlerBase :
51+
/// @include{doc} scripts/docs/en/components_schema/core/src/server/handlers/handler_base.md
4252
///
43-
/// Name | Description | Default value
44-
/// ---- | ----------- | -------------
45-
/// warmup-time-secs | how much time it needs to warmup the server | 0
53+
/// Options inherited from @ref components::ComponentBase :
54+
/// @include{doc} scripts/docs/en/components_schema/core/src/components/impl/component_base.md
4655
class Ping final : public PingBase {
4756
public:
4857
Ping(const components::ComponentConfig& config, const components::ComponentContext& component_context);

‎core/include/userver/server/handlers/tests_control.hpp‎

Lines changed: 11 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -21,23 +21,24 @@ namespace server::handlers {
2121
/// @ingroup userver_components userver_http_handlers
2222
///
2323
/// @brief Handler that allows to control the behavior of server from tests,
24-
/// and @ref scripts/docs/en/userver/functional_testing.md "functional tests with testsuite"
25-
/// in particular.
24+
/// and @ref scripts/docs/en/userver/functional_testing.md "functional tests with testsuite" in particular.
2625
///
2726
/// It is highly recommended to disable this handle in production via the
2827
/// @ref userver_components "load-enabled: false" option.
2928
///
3029
/// The component must be configured in service config.
3130
///
32-
/// ## Static options:
33-
/// Aside from @ref userver_http_handlers "common handler options" component
34-
/// has the following options:
31+
/// ## Static options of server::handlers::TestsControl :
32+
/// @include{doc} scripts/docs/en/components_schema/core/src/server/handlers/tests_control.md
3533
///
36-
/// Name | Description | Default value
37-
/// ---- | ----------- | -------------
38-
/// testpoint-url | an URL that should be notified in the TESTPOINT_CALLBACK and TESTPOINT_CALLBACK_NONCORO macros | -
39-
/// skip-unregistered-testpoints | do not send testpoints data for paths that were not registered by `testpoint-url` | false
40-
/// testpoint-timeout | timeout to use while working with testpoint-url | 1s
34+
/// Options inherited from @ref server::handlers::HttpHandlerBase :
35+
/// @include{doc} scripts/docs/en/components_schema/core/src/server/handlers/http_handler_base.md
36+
///
37+
/// Options inherited from @ref server::handlers::HandlerBase :
38+
/// @include{doc} scripts/docs/en/components_schema/core/src/server/handlers/handler_base.md
39+
///
40+
/// Options inherited from @ref components::ComponentBase :
41+
/// @include{doc} scripts/docs/en/components_schema/core/src/components/impl/component_base.md
4142
///
4243
/// ## Static configuration example:
4344
///

‎core/include/userver/server/websocket/websocket_handler.hpp‎

Lines changed: 10 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -12,28 +12,25 @@ USERVER_NAMESPACE_BEGIN
1212

1313
namespace server::websocket {
1414

15-
// clang-format off
16-
1715
/// @ingroup userver_components userver_http_handlers userver_base_classes
1816
///
1917
/// @brief Base class for WebSocket handler
2018
///
21-
/// ## Static options:
22-
/// Inherits all the options from server::handlers::HandlerBase and adds the
23-
/// following ones:
19+
/// ## Static options of server::websocket::WebsocketHandlerBase :
20+
/// @include{doc} scripts/docs/en/components_schema/core/src/server/websocket/websocket_handler.md
21+
///
22+
/// Options inherited from @ref server::handlers::HttpHandlerBase :
23+
/// @include{doc} scripts/docs/en/components_schema/core/src/server/handlers/http_handler_base.md
2424
///
25-
/// Name | Description | Default value
26-
/// ---- | ----------- | -------------
27-
/// log-level | overrides log level for this handle | `<no override>`
28-
/// status-codes-log-level | map of "status": log_level items to override span log level for specific status codes | {}
29-
/// max-remote-payload | max remote payload size | 65536
30-
/// fragment-size | max output fragment size | 65536
25+
/// Options inherited from @ref server::handlers::HandlerBase :
26+
/// @include{doc} scripts/docs/en/components_schema/core/src/server/handlers/handler_base.md
27+
///
28+
/// Options inherited from @ref components::ComponentBase :
29+
/// @include{doc} scripts/docs/en/components_schema/core/src/components/impl/component_base.md
3130
///
3231
/// ## Example usage:
3332
///
3433
/// @snippet samples/websocket_service/main.cpp Websocket service sample - component
35-
36-
// clang-format on
3734
class WebsocketHandlerBase : public server::handlers::HttpHandlerBase {
3835
public:
3936
WebsocketHandlerBase(const components::ComponentConfig&, const components::ComponentContext&);

‎core/src/server/handlers/auth/digest/auth_checker_settings_component.yaml‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,16 +5,18 @@ properties:
55
algorithm:
66
type: string
77
description: algorithm for hashing nonce
8+
defaultDescription: sha256
89
domains:
910
type: array
1011
description: domains for use
11-
defaultDescription: /
12+
defaultDescription: "['/']"
1213
items:
1314
type: string
1415
description: domain name
1516
qops:
1617
type: array
1718
description: qop-options
19+
defaultDescription: "['auth']"
1820
items:
1921
type: string
2022
description: qop name

0 commit comments

Comments
 (0)