Mercurial > hg > nginx-site
changeset 2028:5c55b7054b58
Updated docs for the upcoming NGINX Plus release.
| author | Ruslan Ermilov <ru@nginx.com> |
|---|---|
| date | Sat, 26 Aug 2017 00:56:05 +0300 |
| parents | dabca59da4ce |
| children | cda19823c33f |
| files | GNUmakefile dtd/module.dtd xml/en/GNUmakefile xml/en/docs/http/ngx_http_api_module_head.xml xml/en/docs/http/ngx_http_keyval_module.xml xml/en/docs/http/ngx_http_status_module.xml xml/en/docs/http/ngx_http_upstream_conf_module.xml xml/en/docs/http/ngx_http_upstream_module.xml xml/en/docs/index.xml xml/ru/docs/http/ngx_http_status_module.xml xml/ru/docs/http/ngx_http_upstream_conf_module.xml xml/ru/docs/http/ngx_http_upstream_module.xml xml/ru/docs/index.xml xsls/body.xsls xslt/body.xslt yaml/nginx_api.yaml yaml/yaml2xml.py |
| diffstat | 17 files changed, 4107 insertions(+), 14 deletions(-) [+] |
line wrap: on
line diff
--- a/GNUmakefile +++ b/GNUmakefile @@ -168,6 +168,16 @@ xslt/%.xslt: xsls/%.xsls mkdir -p $(dir $@) $(call XSLScript, $<, $@) + +xml/en/docs/http/ngx_http_api_module.xml: \ + yaml/nginx_api.yaml \ + yaml/yaml2xml.py \ + xml/en/docs/http/ngx_http_api_module_head.xml + @cat xml/en/docs/http/ngx_http_api_module_head.xml > $@ + @yaml/yaml2xml.py yaml/nginx_api.yaml >> $@ + @echo "</module>" >> $@ + + images: \ binary/books/nginx_troubleshooting.jpg \ binary/books/nginx_richtig_konfigurieren.jpg \ @@ -338,6 +348,7 @@ endif clean: rm -rf $(ZIP) $(OUT) xml/*/docs/dirindex.xml dir.map \ - xml/*/docs/varindex.xml + xml/*/docs/varindex.xml \ + xml/en/docs/http/ngx_http_api_module.xml .DELETE_ON_ERROR:
--- a/dtd/module.dtd +++ b/dtd/module.dtd @@ -83,6 +83,7 @@ <!ELEMENT tag-name ANY > <!ATTLIST tag-name id ID #IMPLIED + name CDATA #IMPLIED > <!ELEMENT tag-desc ANY >
--- a/xml/en/GNUmakefile +++ b/xml/en/GNUmakefile @@ -39,6 +39,7 @@ REFS = \ ngx_core_module \ http/ngx_http_access_module \ http/ngx_http_addition_module \ + http/ngx_http_api_module \ http/ngx_http_auth_basic_module \ http/ngx_http_auth_jwt_module \ http/ngx_http_auth_request_module \ @@ -61,6 +62,7 @@ REFS = \ http/ngx_http_image_filter_module \ http/ngx_http_index_module \ http/ngx_http_js_module \ + http/ngx_http_keyval_module \ http/ngx_http_limit_conn_module \ http/ngx_http_limit_req_module \ http/ngx_http_log_module \
new file mode 100644 --- /dev/null +++ b/xml/en/docs/http/ngx_http_api_module_head.xml @@ -0,0 +1,161 @@ +<?xml version="1.0"?> + +<!-- + Copyright (C) Nginx, Inc. + --> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Module ngx_http_api_module" + link="/en/docs/http/ngx_http_api_module.html" + lang="en" + rev="1"> + +<section id="summary"> + +<para> +The <literal>ngx_http_api_module</literal> module (1.13.3) provides REST API +for accessing various status information, +configuring upstream server groups on-the-fly, and managing +<link doc="ngx_http_keyval_module.xml">key-value pairs</link> +without the need of reconfiguring nginx. +</para> + +<para> +<note> +The module supersedes the +<link doc="ngx_http_status_module.xml">ngx_http_status_module</link> and +<link doc="ngx_http_upstream_conf_module.xml">ngx_http_upstream_conf_module</link> +modules. +</note> +</para> + +<para> +<note> +This module is available as part of our +<commercial_version>commercial subscription</commercial_version>. +</note> +</para> + +</section> + + +<section id="example" name="Example Configuration"> + +<para> +<example> +http { + upstream backend { + zone http_backend 64k; + + server backend1.example.com weight=5; + server backend2.example.com; + } + + proxy_cache_path /data/nginx/cache_backend keys_zone=cache_backend:10m; + + server { + server_name backend.example.com; + + location / { + proxy_pass http://backend; + proxy_cache cache_backend; + + health_check; + } + + status_zone server_backend; + } + + keyval_zone zone=one:32k state=one.keyval; + keyval $arg_text $text zone=one; + + server { + listen 127.0.0.1; + + location /api { + <emphasis>api</emphasis> write=on; + allow 127.0.0.1; + deny all; + } + } +} + +stream { + upstream backend { + zone stream_backend 64k; + + server backend1.example.com:12345 weight=5; + server backend2.example.com:12345; + } + + server { + listen 127.0.0.1:12345; + proxy_pass backend; + status_zone server_backend; + health_check; + } +} +</example> +All API requests include a supported API version in the URI. +Examples of API requests with this configuration: +<example> +http://127.0.0.1/api/1/ +http://127.0.0.1/api/1/nginx +http://127.0.0.1/api/1/connections +http://127.0.0.1/api/1/http/requests +http://127.0.0.1/api/1/http/server_zones/server_backend +http://127.0.0.1/api/1/http/caches/cache_backend +http://127.0.0.1/api/1/http/upstreams/backend +http://127.0.0.1/api/1/http/upstreams/backend/servers/ +http://127.0.0.1/api/1/http/upstreams/backend/servers/1 +http://127.0.0.1/api/1/http/keyvals/one?key=arg1 +http://127.0.0.1/api/1/stream/ +http://127.0.0.1/api/1/stream/server_zones/server_backend +http://127.0.0.1/api/1/stream/upstreams/ +http://127.0.0.1/api/1/stream/upstreams/backend +http://127.0.0.1/api/1/stream/upstreams/backend/servers/1 +</example> +</para> + +</section> + + +<section id="directives" name="Directives"> + +<directive name="api"> +<syntax> +[<literal>write</literal>=<literal>on</literal>|<literal>off</literal>]</syntax> +<default/> +<context>location</context> + +<para> +Turns on the REST API interface in the surrounding location. +Access to this location should be +<link doc="ngx_http_core_module.xml" id="satisfy">limited</link>. +</para> + +<para> +The <literal>write</literal> parameter determines whether the API +is read-only or read-write. +By default, the API is read-only. +</para> + +<para> +All API requests should contain a supported API version in the URI. +If the request URI equals the location prefix, +the list of supported API versions is returned. +The current and the only API version is “<literal>1</literal>”. +</para> + +<para> +The optional “<literal>fields</literal>” argument in the request line +specifies which fields of the requested objects will be output: +<example> +http://127.0.0.1/api/1/nginx?fields=version,build +</example> +</para> + +</directive> + +</section>
new file mode 100644 --- /dev/null +++ b/xml/en/docs/http/ngx_http_keyval_module.xml @@ -0,0 +1,103 @@ +<?xml version="1.0"?> + +<!-- + Copyright (C) Nginx, Inc. + --> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Module ngx_http_keyval_module" + link="/en/docs/http/ngx_http_keyval_module.html" + lang="en" + rev="1"> + +<section id="summary"> + +<para> +The <literal>ngx_http_keyval_module</literal> module (1.13.3) creates variables +with values taken from key-value pairs managed by the +<link doc="ngx_http_api_module.xml" id="http_keyvals">API</link>. +</para> + +<para> +<note> +This module is available as part of our +<commercial_version>commercial subscription</commercial_version>. +</note> +</para> + +</section> + + +<section id="example" name="Example Configuration"> + +<para> +<example> +http { + + keyval_zone zone=one:32k state=one.keyval; + keyval $arg_text $text zone=one; + ... + server { + ... + location / { + return 200 $text; + } + + location /api { + api write=on; + } + } +} +</example> +</para> + +</section> + + +<section id="directives" name="Directives"> + +<directive name="keyval"> +<syntax> + <value>key</value> + <value>$variable</value> + <literal>zone</literal>=<value>name</value></syntax> +<default/> +<context>http</context> + +<para> +Creates a new <value>$variable</value> whose value +is looked up by the <value>key</value> in the key-value database. +Strings are matched ignoring the case. +The database is stored in a shared memory zone +specified by the <literal>zone</literal> parameter. +</para> + +</directive> + + +<directive name="keyval_zone"> +<syntax> + <literal>zone</literal>=<value>name</value>:<value>size</value> + [<literal>state</literal>=<value>file</value>]</syntax> +<default/> +<context>http</context> + +<para> +Sets the <value>name</value> and <value>size</value> of the shared memory zone +that keeps the key-value database. +Key-value pairs are managed by the +<link doc="ngx_http_api_module.xml" id="http_keyvals">API</link>. +</para> + +<para> +The optional <literal>state</literal> parameter specifies a <value>file</value> +that keeps the current state of the key-value database in the JSON format +and makes it persistent across nginx restarts. +</para> + +</directive> + +</section> + +</module>
--- a/xml/en/docs/http/ngx_http_status_module.xml +++ b/xml/en/docs/http/ngx_http_status_module.xml @@ -9,13 +9,18 @@ <module name="Module ngx_http_status_module" link="/en/docs/http/ngx_http_status_module.html" lang="en" - rev="16"> + rev="17"> <section id="summary"> <para> The <literal>ngx_http_status_module</literal> module provides access to various status information. +<note> +This module was superseded by the +<link doc="ngx_http_api_module.xml">ngx_http_api_module</link> module +in 1.13.0. +</note> </para> <para> @@ -895,6 +900,12 @@ or The current number of connections. </tag-desc> +<tag-name><literal>max_conns</literal></tag-name> +<tag-desc> +The <link doc="../stream/ngx_stream_upstream_module.xml" id="max_conns"/> limit +for the server. +</tag-desc> + <tag-name><literal>connections</literal></tag-name> <tag-desc> The total number of
--- a/xml/en/docs/http/ngx_http_upstream_conf_module.xml +++ b/xml/en/docs/http/ngx_http_upstream_conf_module.xml @@ -9,7 +9,7 @@ <module name="Module ngx_http_upstream_conf_module" link="/en/docs/http/ngx_http_upstream_conf_module.html" lang="en" - rev="3"> + rev="4"> <section id="summary"> @@ -23,6 +23,11 @@ or <link doc="../stream/ngx_stream_upstream_module.xml" id="zone">stream</link> server group must reside in the shared memory. <note> +This module was superseded by the +<link doc="ngx_http_api_module.xml">ngx_http_api_module</link> module +in 1.13.0. +</note> +<note> This module is available as part of our <commercial_version>commercial subscription</commercial_version>. </note>
--- a/xml/en/docs/http/ngx_http_upstream_module.xml +++ b/xml/en/docs/http/ngx_http_upstream_module.xml @@ -10,7 +10,7 @@ <module name="Module ngx_http_upstream_module" link="/en/docs/http/ngx_http_upstream_module.html" lang="en" - rev="60"> + rev="61"> <section id="summary"> @@ -798,7 +798,8 @@ This directive is available as part of o <literal>create=</literal><value>$variable</value> <literal>lookup=</literal><value>$variable</value> <literal>zone=</literal><value>name</value>:<value>size</value> - [<literal>timeout=</literal><value>time</value>]</syntax> + [<literal>timeout=</literal><value>time</value>] + [<literal>header</literal>]</syntax> <default/> <context>upstream</context> <appeared-in>1.5.7</appeared-in> @@ -965,6 +966,11 @@ The sessions that are not accessed durin By default, <literal>timeout</literal> is set to 10 minutes. </para> +<para id="sticky_learn_header"> +The <literal>header</literal> parameter (1.13.1) allows creating a session +right after receiving response headers from the upstream server. +</para> + </tag-desc> </list> </para>
--- a/xml/en/docs/index.xml +++ b/xml/en/docs/index.xml @@ -8,7 +8,7 @@ <article name="nginx documentation" link="/en/docs/" lang="en" - rev="40" + rev="41" toc="no"> @@ -215,6 +215,11 @@ ngx_http_addition_module</link> </listitem> <listitem> +<link doc="http/ngx_http_api_module.xml"> +ngx_http_api_module</link> +</listitem> + +<listitem> <link doc="http/ngx_http_auth_basic_module.xml"> ngx_http_auth_basic_module</link> </listitem> @@ -320,6 +325,11 @@ ngx_http_js_module</link> </listitem> <listitem> +<link doc="http/ngx_http_keyval_module.xml"> +ngx_http_keyval_module</link> +</listitem> + +<listitem> <link doc="http/ngx_http_limit_conn_module.xml"> ngx_http_limit_conn_module</link> </listitem>
--- a/xml/ru/docs/http/ngx_http_status_module.xml +++ b/xml/ru/docs/http/ngx_http_status_module.xml @@ -9,13 +9,18 @@ <module name="Модуль ngx_http_status_module" link="/ru/docs/http/ngx_http_status_module.html" lang="ru" - rev="16"> + rev="17"> <section id="summary"> <para> Модуль <literal>ngx_http_status_module</literal> предоставляет доступ к информации о состоянии сервера. +<note> +Этот модуль был заменён модулем +<link doc="ngx_http_api_module.xml">ngx_http_api_module</link> +в версии 1.13.0. +</note> </para> <para> @@ -890,6 +895,13 @@ 2xx, 4xx или 5xx. Текущее число соединений. </tag-desc> +<tag-name><literal>max_conns</literal></tag-name> +<tag-desc> +Ограничение +<link doc="../stream/ngx_stream_upstream_module.xml" id="max_conns"/> +для сервера. +</tag-desc> + <tag-name><literal>connections</literal></tag-name> <tag-desc> Суммарное число
--- a/xml/ru/docs/http/ngx_http_upstream_conf_module.xml +++ b/xml/ru/docs/http/ngx_http_upstream_conf_module.xml @@ -9,7 +9,7 @@ <module name="Модуль ngx_http_upstream_conf_module" link="/ru/docs/http/ngx_http_upstream_conf_module.html" lang="ru" - rev="3"> + rev="4"> <section id="summary"> @@ -22,9 +22,11 @@ или <link doc="../stream/ngx_stream_upstream_module.xml" id="zone">stream</link> должна находиться в разделяемой памяти. -</para> - -<para> +<note> +Этот модуль был заменён модулем +<link doc="ngx_http_api_module.xml">ngx_http_api_module</link> +в версии 1.13.0. +</note> <note> Модуль доступен как часть <commercial_version>коммерческой подписки</commercial_version>.
--- a/xml/ru/docs/http/ngx_http_upstream_module.xml +++ b/xml/ru/docs/http/ngx_http_upstream_module.xml @@ -10,7 +10,7 @@ <module name="Модуль ngx_http_upstream_module" link="/ru/docs/http/ngx_http_upstream_module.html" lang="ru" - rev="60"> + rev="61"> <section id="summary"> @@ -805,7 +805,8 @@ server { <literal>create=</literal><value>$переменная</value> <literal>lookup=</literal><value>$переменная</value> <literal>zone=</literal><value>имя</value>:<value>размер</value> - [<literal>timeout=</literal><value>время</value>]</syntax> + [<literal>timeout=</literal><value>время</value>] + [<literal>header</literal>]</syntax> <default/> <context>upstream</context> <appeared-in>1.5.7</appeared-in> @@ -971,6 +972,11 @@ upstream backend { По умолчанию <literal>timeout</literal> равен 10 минутам. </para> +<para id="sticky_learn_header"> +Параметр <literal>header</literal> (1.13.1) позволяет создавать сессию +сразу после получения заголовков ответа от сервера группы. +</para> + </tag-desc> </list> </para>
--- a/xml/ru/docs/index.xml +++ b/xml/ru/docs/index.xml @@ -8,7 +8,7 @@ <article name="nginx: документация" link="/ru/docs/" lang="ru" - rev="40" + rev="41" toc="no"> @@ -164,6 +164,11 @@ rewrite-правил</link> [en] <link doc="contributing_changes.xml"/> </listitem> +<listitem> +<link doc="../../en/docs/dev/development_guide.xml">Руководство +по разработке</link> [en] +</listitem> + </list> </para> @@ -215,6 +220,11 @@ ngx_http_addition_module</link> </listitem> <listitem> +<link doc="http/ngx_http_api_module.xml"> +ngx_http_api_module</link> [en] +</listitem> + +<listitem> <link doc="http/ngx_http_auth_basic_module.xml"> ngx_http_auth_basic_module</link> </listitem> @@ -320,6 +330,11 @@ ngx_http_js_module</link> </listitem> <listitem> +<link doc="http/ngx_http_keyval_module.xml"> +ngx_http_keyval_module</link> [en] +</listitem> + +<listitem> <link doc="http/ngx_http_limit_conn_module.xml"> ngx_http_limit_conn_module</link> </listitem>
--- a/xsls/body.xsls +++ b/xsls/body.xsls @@ -80,6 +80,13 @@ X:template body (lang) { <a href="#{@name}"> !{@name} </a><br/> } } + X:if "@id = 'endpoints'" { + X:for-each "para/list/tag-name[@name]" { + X:text{     } + <a href="#{@id}"> !{@name} </a><br/> + } + } + } </td></tr></table> }
--- a/xslt/body.xslt +++ b/xslt/body.xslt @@ -80,6 +80,13 @@ <a href="#{@name}"> <xsl:value-of select="@name"/> </a><br/> </xsl:for-each> </xsl:if> + <xsl:if test="@id = 'endpoints'"> + <xsl:for-each select="para/list/tag-name[@name]"> + <xsl:text>     </xsl:text> + <a href="#{@id}"> <xsl:value-of select="@name"/> </a><br/> + </xsl:for-each> + </xsl:if> + </xsl:for-each> </td></tr></table> </xsl:if>
new file mode 100644 --- /dev/null +++ b/yaml/nginx_api.yaml @@ -0,0 +1,3211 @@ +swagger: '2.0' +info: + version: '1.0' + title: NGINX Plus REST API + description: | + NGINX Plus REST + [API](https://nginx.org/en/docs/http/ngx_http_api_module.html) + provides access to NGINX Plus status information, + on-the-fly configuration of upstream servers and + [key-value](https://nginx.org/en/docs/http/ngx_http_keyval_module.html) + pairs management. +basePath: /api/1 +tags: + - name: General Info + - name: Processes + - name: Connections + - name: SSL + - name: Slabs + - name: HTTP + - name: HTTP Requests + - name: HTTP Caches + - name: HTTP Server Zones + - name: HTTP Upstreams + - name: HTTP Keyvals + - name: Stream + - name: Stream Server Zones + - name: Stream Upstreams + - name: Method GET + - name: Method POST + - name: Method PATCH + - name: Method DELETE +schemes: + - http +paths: + /: + get: + tags: + - General Info + - Method GET + summary: | + Return list of root endpoints + description: | + Returns a list of root endpoints. + operationId: getAPIEndpoints + produces: + - application/json + responses: + '200': + description: Success + schema: + $ref: '#/definitions/ArrayOfStrings' + /nginx: + get: + tags: + - General Info + - Method GET + summary: | + Return status of nginx running instance + description: | + Returns nginx version, build name, address, + number of configuration reloads, IDs of master and worker processes. + operationId: getNginx + produces: + - application/json + parameters: + - in: query + name: fields + type: string + description: | + Limits which fields of nginx running instance will be output. + responses: + '200': + description: Success + schema: + $ref: '#/definitions/NginxObject' + /processes: + get: + tags: + - Processes + - Method GET + summary: | + Return nginx processes status + description: | + Returns the number of abnormally terminated + and respawned child processes. + operationId: getProcesses + produces: + - application/json + responses: + '200': + description: Success + schema: + $ref: '#/definitions/NginxProcesses' + delete: + tags: + - Processes + - Method DELETE + summary: | + Reset nginx processes statistics + description: | + Resets counters of abnormally terminated and respawned + child processes. + operationId: deleteProcesses + responses: + '204': + description: Success + /connections: + get: + tags: + - Connections + - Method GET + summary: | + Return client connections statistics + description: | + Returns statistics of client connections. + operationId: getConnections + produces: + - application/json + responses: + '200': + description: Success + schema: + $ref: '#/definitions/NginxConnections' + parameters: + - in: query + name: fields + type: string + description: | + Limits which fields of the connections statistics will be output. + delete: + tags: + - Connections + - Method DELETE + summary: | + Reset client connections statistics + description: | + Resets statistics of accepted and dropped + client connections. + operationId: deleteConnections + responses: + '204': + description: Success + /ssl: + get: + tags: + - SSL + - Method GET + summary: | + Return SSL statistics + description: | + Returns SSL statistics. + operationId: getSsl + produces: + - application/json + responses: + '200': + description: Success + schema: + $ref: '#/definitions/NginxSSLObject' + parameters: + - in: query + name: fields + type: string + description: | + Limits which fields of SSL statistics will be output. + delete: + tags: + - SSL + - Method DELETE + summary: | + Reset SSL statistics + description: | + Resets counters of SSL handshakes and session reuses. + operationId: deleteSslStat + responses: + '204': + description: Success + /slabs/: + get: + tags: + - Slabs + - Method GET + summary: | + Return status of all slabs + description: | + Returns status of slabs + for each shared memory zone with slab allocator. + operationId: getSlabs + produces: + - application/json + parameters: + - in: query + name: fields + type: string + description: | + Limits which fields of slab zones will be output. + If the “<literal>fields</literal>” value is empty, + then only zone names are output. + responses: + '200': + description: Success + schema: + $ref: '#/definitions/NginxSlabZoneMap' + '/slabs/{slabZoneName}': + parameters: + - name: slabZoneName + in: path + description: | + The name of the shared memory zone with slab allocator. + required: true + type: string + get: + tags: + - Slabs + - Method GET + summary: | + Return status of a slab + description: | + Returns status of slabs for a particular shared memory zone + with slab allocator. + operationId: getSlabZone + produces: + - application/json + parameters: + - in: query + name: fields + type: string + description: | + Limits which fields of the slab zone will be output. + responses: + '200': + description: Success + schema: + $ref: '#/definitions/NginxSlabZone' + '404': + description: Slab not found (*SlabNotFound*) + schema: + $ref: '#/definitions/NginxError' + delete: + tags: + - Slabs + - Method DELETE + summary: | + Reset slab statistics + description: | + Resets the “<literal>reqs</literal>” and “<literal>fails</literal>” + metrics for each memory slot. + operationId: deleteSlabZoneStats + responses: + '204': + description: Success + '404': + description: Slab not found (*SlabNotFound*) + schema: + $ref: '#/definitions/NginxError' + /http/: + get: + tags: + - HTTP + - Method GET + summary: | + Return list of HTTP-related endpoints + description: | + Returns a list of first level HTTP endpoints. + operationId: getHttp + produces: + - application/json + responses: + '200': + description: Success + schema: + $ref: '#/definitions/ArrayOfStrings' + /http/requests: + get: + tags: + - HTTP Requests + - Method GET + summary: | + Return HTTP requests statistics + description: | + Returns status of client HTTP requests. + operationId: getHttpRequests + produces: + - application/json + parameters: + - in: query + name: fields + type: string + description: | + Limits which fields of client HTTP requests statistics + will be output. + responses: + '200': + description: Success + schema: + $ref: '#/definitions/NginxHTTPRequests' + delete: + tags: + - HTTP Requests + - Method DELETE + summary: | + Reset HTTP requests statistics + description: | + Resets the number of total client HTTP requests. + operationId: deleteHttpRequests + responses: + '204': + description: Success + /http/server_zones/: + get: + tags: + - HTTP Server Zones + - Method GET + summary: | + Return status of all HTTP server zones + description: | + Returns status information for each HTTP + [server zone](https://nginx.org/en/docs/http/ngx_http_status_module.html#status_zone). + operationId: getHttpServerZones + produces: + - application/json + parameters: + - in: query + name: fields + type: string + description: | + Limits which fields of server zones will be output. + If the “<literal>fields</literal>” value is empty, + then only server zone names are output. + responses: + '200': + description: Success + schema: + $ref: '#/definitions/NginxHTTPServerZonesMap' + '/http/server_zones/{httpServerZoneName}': + parameters: + - name: httpServerZoneName + in: path + description: The name of an HTTP server zone. + type: string + required: true + get: + tags: + - HTTP Server Zones + - Method GET + summary: | + Return status of an HTTP server zone + description: | + Returns status of a particular HTTP server zone. + operationId: getHttpServerZone + produces: + - application/json + parameters: + - name: fields + in: query + type: string + description: | + Limits which fields of the server zone will be output. + responses: + '200': + description: Success + schema: + $ref: '#/definitions/NginxHTTPServerZone' + '404': + description: Server zone not found (*ServerZoneNotFound*) + schema: + $ref: '#/definitions/NginxError' + delete: + tags: + - HTTP Server Zones + - Method DELETE + summary: | + Reset statistics for an HTTP server zone + description: | + Resets statistics of accepted and discarded requests, responses, + received and sent bytes in a particular HTTP server zone. + operationId: deleteHttpServerZoneStat + responses: + '204': + description: Success + '404': + description: Server zone not found (*ServerZoneNotFound*) + schema: + $ref: '#/definitions/NginxError' + /http/caches/: + get: + tags: + - HTTP Caches + - Method GET + summary: | + Return status of all caches + description: | + Returns status of each cache configured by + [proxy_cache_path](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_path) + and other “<literal>*_cache_path</literal>” directives. + operationId: getHttpCaches + produces: + - application/json + parameters: + - name: fields + in: query + type: string + description: | + Limits which fields of cache zones will be output. + If the “<literal>fields</literal>” value is empty, + then only names of cache zones are output. + responses: + '200': + description: Success + schema: + $ref: '#/definitions/NginxHTTPCachesMap' + '/http/caches/{httpCacheZoneName}': + parameters: + - name: httpCacheZoneName + in: path + description: | + The name of the cache zone. + type: string + required: true + get: + tags: + - HTTP Caches + - Method GET + summary: | + Return status of a cache + description: | + Returns status of a particular cache. + operationId: getHttpCacheZone + produces: + - application/json + parameters: + - name: fields + in: query + type: string + description: | + Limits which fields of the cache zone will be output. + responses: + '200': + description: Success + schema: + $ref: '#/definitions/NginxHTTPCache' + '404': + description: Cache not found (*CacheNotFound*) + schema: + $ref: '#/definitions/NginxError' + delete: + tags: + - HTTP Caches + - Method DELETE + summary: | + Reset cache statistics + description: | + Resets statistics of cache hits/misses in a particular cache zone. + operationId: deleteHttpCacheZoneStat + responses: + '204': + description: Success + '404': + description: Cache not found (*CacheNotFound*) + schema: + $ref: '#/definitions/NginxError' + /http/upstreams/: + get: + tags: + - HTTP Upstreams + - Method GET + summary: | + Return status of all HTTP upstream server groups + description: | + Returns status of each HTTP upstream server group + and its servers. + operationId: getHttpUpstreams + produces: + - application/json + parameters: + - name: fields + in: query + type: string + description: | + Limits which fields of upstream server groups will be output. + If the “<literal>fields</literal>” value is empty, + only names of upstreams are output. + responses: + '200': + description: Success + schema: + $ref: '#/definitions/NginxHTTPUpstreamMap' + '/http/upstreams/{httpUpstreamName}/': + parameters: + - name: httpUpstreamName + in: path + description: | + The name of an HTTP upstream server group. + required: true + type: string + get: + tags: + - HTTP Upstreams + - Method GET + summary: | + Return status of an HTTP upstream server group + description: | + Returns status of a particular HTTP upstream server group + and its servers. + operationId: getHttpUpstreamName + produces: + - application/json + parameters: + - name: fields + in: query + type: string + description: | + Limits which fields of the upstream server group will be output. + responses: + '200': + description: Success + schema: + $ref: '#/definitions/NginxHTTPUpstream' + '400': + description: | + Upstream is static (*UpstreamStatic*) + schema: + $ref: '#/definitions/NginxError' + '404': + description: | + Upstream not found (*UpstreamNotFound*) + schema: + $ref: '#/definitions/NginxError' + delete: + tags: + - HTTP Upstreams + - Method DELETE + summary: | + Reset statistics of an HTTP upstream server group + description: | + Resets the statistics for each upstream server + in an upstream server group and queue statistics. + operationId: deleteHttpUpstreamStat + produces: + - application/json + responses: + '204': + description: Success + '400': + description: | + Upstream is static (*UpstreamStatic*) + schema: + $ref: '#/definitions/NginxError' + '404': + description: | + Upstream not found (*UpstreamNotFound*) + schema: + $ref: '#/definitions/NginxError' + '/http/upstreams/{httpUpstreamName}/servers/': + parameters: + - name: httpUpstreamName + in: path + description: | + The name of an upstream server group. + required: true + type: string + get: + tags: + - HTTP Upstreams + - Method GET + summary: | + Return configuration of all servers in an HTTP upstream server group + description: | + Returns configuration of each server + in a particular HTTP upstream server group. + operationId: getHttpUpstreamServers + produces: + - application/json + responses: + '200': + description: Success + schema: + $ref: '#/definitions/NginxHTTPUpstreamConfServerMap' + '400': + description: | + Upstream is static (*UpstreamStatic*) + schema: + $ref: '#/definitions/NginxError' + '404': + description: | + Upstream not found (*UpstreamNotFound*) + schema: + $ref: '#/definitions/NginxError' + post: + tags: + - HTTP Upstreams + - Method POST + summary: | + Add a server to an HTTP upstream server group + description: | + Adds a new server to an HTTP upstream server group. + Server parameters are specified in the JSON format. + operationId: postHttpUpstreamServer + produces: + - application/json + parameters: + - in: body + name: postHttpUpstreamServer + description: | + Address of a new server and other optional parameters + in the JSON format. + The “*ID*”, “*backup*”, and “*service*” parameters + cannot be changed. + required: true + schema: + $ref: '#/definitions/NginxHTTPUpstreamConfServer' + responses: + '201': + description: Created + schema: + $ref: '#/definitions/NginxHTTPUpstreamConfServer' + '400': + description: | + Upstream is static (*UpstreamStatic*), + invalid “**parameter**” value (*UpstreamConfFormatError*), + missing “*server*” argument (*UpstreamConfFormatError*), + unknown parameter “**name**” (*UpstreamConfFormatError*), + nested object or list (*UpstreamConfFormatError*), + “*error*” while parsing (*UpstreamBadAddress*), + service upstream “*host*” may not have port (*UpstreamBadAddress*), + service upstream “*host*” requires domain name (*UpstreamBadAddress*), + invalid “*weight*” (*UpstreamBadWeight*), + invalid “*max_conns*” (*UpstreamBadMaxConns*), + invalid “*max_fails*” (*UpstreamBadMaxFails*), + invalid “*fail_timeout*” (*UpstreamBadFailTimeout*), + invalid “*slow_start*” (*UpstreamBadSlowStart*), + route is too long (*UpstreamBadRoute*), + “*service*” is empty (*UpstreamBadService*), + no resolver defined to resolve (*UpstreamConfNoResolver*), + upstream “**name**” has no backup (*UpstreamNoBackup*), + upstream “**name**” memory exhausted (*UpstreamOutOfMemory*) + schema: + $ref: '#/definitions/NginxError' + '404': + description: | + Upstream not found (*UpstreamNotFound*) + schema: + $ref: '#/definitions/NginxError' + '415': + description: JSON error (*JsonError*) + schema: + $ref: '#/definitions/NginxError' + '/http/upstreams/{httpUpstreamName}/servers/{httpUpstreamServerId}': + parameters: + - name: httpUpstreamName + in: path + description: | + The name of the upstream server group. + required: true + type: string + - name: httpUpstreamServerId + in: path + description: | + The ID of the server. + required: true + type: string + get: + tags: + - HTTP Upstreams + - Method GET + summary: | + Return configuration of a server in an HTTP upstream server group + description: | + Returns configuration of a particular server + in the HTTP upstream server group. + operationId: getHttpUpstreamPeer + produces: + - application/json + responses: + '200': + description: Success + schema: + $ref: '#/definitions/NginxHTTPUpstreamConfServer' + '400': + description: | + Upstream is static (*UpstreamStatic*), + invalid server ID (*UpstreamBadServerId*) + schema: + $ref: '#/definitions/NginxError' + '404': + description: | + Upstream not found (*UpstreamNotFound*), + server with ID “**id**” does not exist (*UpstreamServerNotFound*) + schema: + $ref: '#/definitions/NginxError' + patch: + tags: + - HTTP Upstreams + - Method PATCH + summary: | + Modify a server in an HTTP upstream server group + description: | + Modifies settings of a particular server + in an HTTP upstream server group. + Server parameters are specified in the JSON format. + operationId: patchHttpUpstreamPeer + produces: + - application/json + parameters: + - in: body + name: patchHttpUpstreamServer + description: | + Server parameters, specified in the JSON format. + The “*ID*”, “*backup*”, and “*service*” parameters + cannot be changed. + required: true + schema: + $ref: '#/definitions/NginxHTTPUpstreamConfServer' + responses: + '200': + description: Success + schema: + $ref: '#/definitions/NginxHTTPUpstreamConfServer' + '400': + description: | + Upstream is static (*UpstreamStatic*), + invalid “**parameter**” value (*UpstreamConfFormatError*), + unknown parameter “**name**” (*UpstreamConfFormatError*), + nested object or list (*UpstreamConfFormatError*), + “*error*” while parsing (*UpstreamBadAddress*), + invalid “*server*” argument (*UpstreamBadAddress*), + invalid server ID (*UpstreamBadServerId*), + invalid “*weight*” (*UpstreamBadWeight*), + invalid “*max_conns*” (*UpstreamBadMaxConns*), + invalid “*max_fails*” (*UpstreamBadMaxFails*), + invalid “*fail_timeout*” (*UpstreamBadFailTimeout*), + invalid “*slow_start*” (*UpstreamBadSlowStart*), + route is too long (*UpstreamBadRoute*), + “*service*” is empty (*UpstreamBadService*), + server “**ID**” address is immutable (*UpstreamServerImmutable*), + server “*ID*” weight is immutable (*UpstreamServerWeightImmutable*), + upstream “*name*” memory exhausted (*UpstreamOutOfMemory*) + schema: + $ref: '#/definitions/NginxError' + '404': + description: | + Upstream not found (*UpstreamNotFound*), + server with ID “**id**” does not exist (*UpstreamServerNotFound*) + schema: + $ref: '#/definitions/NginxError' + '415': + description: JSON error (*JsonError*) + schema: + $ref: '#/definitions/NginxError' + delete: + tags: + - HTTP Upstreams + - Method DELETE + summary: | + Remove a server from an HTTP upstream server group + description: | + Removes a server from an HTTP upstream server group. + operationId: deleteHttpUpstreamServer + produces: + - application/json + responses: + '200': + description: Success + schema: + $ref: '#/definitions/NginxHTTPUpstreamConfServerMap' + '400': + description: | + Upstream is static (*UpstreamStatic*), + invalid server ID (*UpstreamBadServerId*), + server “**id**” not removable (*UpstreamServerImmutable*) + schema: + $ref: '#/definitions/NginxError' + '404': + description: | + Upstream not found (*UpstreamNotFound*), + server with ID “**id**” does not exist (*UpstreamServerNotFound*) + schema: + $ref: '#/definitions/NginxError' + /http/keyvals/: + get: + tags: + - HTTP Keyvals + - Method GET + summary: | + Return key-value pairs from all keyval zones + description: | + Returns key-value pairs for each keyval shared memory + [zone](https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_zone). + operationId: getHttpKeyvalZones + produces: + - application/json + parameters: + - name: fields + in: query + type: string + description: | + If the “<literal>fields</literal>” value is empty, + then only keyval zone names are output. + responses: + '200': + description: Success + schema: + $ref: '#/definitions/NginxHTTPKeyvalZonesMap' + '/http/keyvals/{httpKeyvalZoneName}': + parameters: + - name: httpKeyvalZoneName + in: path + description: | + The name of a keyval shared memory zone. + required: true + type: string + get: + tags: + - HTTP Keyvals + - Method GET + summary: | + Return key-value pairs from a keyval zone + description: | + Returns key-value pairs stored in a particular keyval shared memory + [zone](https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_zone). + operationId: getHttpKeyvalZoneKeysValues + produces: + - application/json + parameters: + - name: key + in: query + type: string + description: | + Get a particular key-value pair from the keyval zone. + responses: + '200': + description: Success + schema: + $ref: '#/definitions/NginxHTTPKeyvalZone' + '404': + description: | + Keyval not found (*KeyvalNotFound*), + keyval key not found (*KeyvalKeyNotFound*) + schema: + $ref: '#/definitions/NginxError' + post: + tags: + - HTTP Keyvals + - Method POST + summary: | + Add a key-value pair to the keyval zone + description: | + Adds a new key-value pair to the keyval shared memory + [zone](https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_zone). + Several key-value pairs can be entered + if the keyval shared memory zone is empty. + operationId: postHttpKeyvalZoneData + produces: + - application/json + parameters: + - in: body + name: Key-value + description: | + A key-value pair is specified in the JSON format. + Several key-value pairs can be entered + if the keyval shared memory zone is empty. + required: true + schema: + $ref: '#/definitions/NginxHTTPKeyvalZone' + responses: + '201': + description: Created + '400': + description: | + Key required (*KeyvalFormatError*), + only one key can be added (*KeyvalFormatError*), + nested object or list (*KeyvalFormatError*) + schema: + $ref: '#/definitions/NginxError' + '404': + description: Keyval not found (*KeyvalNotFound*) + schema: + $ref: '#/definitions/NginxError' + '409': + description: Key already exists (*KeyvalKeyExists*) + schema: + $ref: '#/definitions/NginxError' + '415': + description: JSON error (*JsonError*) + schema: + $ref: '#/definitions/NginxError' + patch: + tags: + - HTTP Keyvals + - Method PATCH + summary: | + Modify a key-value or delete a key + description: | + Changes the value of the selected key in the key-value pair + or deletes a key by setting the key value to <literal>null</literal>. + operationId: patchHttpKeyvalZoneKeyValue + produces: + - application/json + parameters: + - in: body + name: httpKeyvalZoneKeyValue + description: | + A new value for the key is specified in the JSON format. + required: true + schema: + $ref: '#/definitions/NginxHTTPKeyvalZone' + responses: + '204': + description: Success + '400': + description: | + Key required (*KeyvalFormatError*), + only one key can be updated (*KeyvalFormatError*), + nested object or list (*KeyvalFormatError*) + schema: + $ref: '#/definitions/NginxError' + '404': + description: | + Keyval not found (*KeyvalNotFound*), + keyval key not found (*KeyvalKeyNotFound*) + schema: + $ref: '#/definitions/NginxError' + '415': + description: JSON error (*JsonError*) + schema: + $ref: '#/definitions/NginxError' + delete: + tags: + - HTTP Keyvals + - Method DELETE + summary: | + Empty the keyval zone + description: | + Deletes all key-value pairs from the keyval shared memory + [zone](https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_zone). + operationId: deleteHttpKeyvalZoneData + responses: + '204': + description: Success + '404': + description: Keyval not found (*KeyvalNotFound*) + schema: + $ref: '#/definitions/NginxError' + /stream/: + get: + tags: + - Stream + summary: | + Return list of stream-related endpoints + description: | + Returns a list of first level stream endpoints. + operationId: getStream + produces: + - application/json + responses: + '200': + description: Success + schema: + $ref: '#/definitions/ArrayOfStrings' + /stream/server_zones/: + get: + tags: + - Stream Server Zones + - Method GET + summary: | + Return status of all stream server zones + description: | + Returns status information for each stream + [server zone](https://nginx.org/en/docs/http/ngx_http_status_module.html#status_zone). + operationId: getStreamServerZones + produces: + - application/json + parameters: + - name: fields + in: query + type: string + description: | + Limits which fields of server zones will be output. + If the “<literal>fields</literal>” value is empty, + then only server zone names are output. + responses: + '200': + description: Success + schema: + $ref: '#/definitions/NginxStreamServerZonesMap' + '404': + description: | + [stream](https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream) + not configured (*StreamNotConfigured*) + schema: + $ref: '#/definitions/NginxError' + '/stream/server_zones/{streamServerZoneName}': + parameters: + - name: streamServerZoneName + in: path + description: | + The name of a stream server zone. + type: string + required: true + get: + tags: + - Stream Server Zones + - Method GET + summary: | + Return status of a stream server zone + description: | + Returns status of a particular stream server zone. + operationId: getStreamServerZone + produces: + - application/json + parameters: + - name: fields + in: query + type: string + description: | + Limits which fields of the server zone will be output. + responses: + '200': + description: Success + schema: + $ref: '#/definitions/NginxStreamServerZone' + '404': + description: | + Server zone not found (*ServerZoneNotFound*), + [stream](https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream) + not configured (*StreamNotConfigured*) + schema: + $ref: '#/definitions/NginxError' + delete: + tags: + - Stream Server Zones + - Method DELETE + summary: | + Reset statistics for a stream server zone + description: | + Resets statistics of accepted and discarded connections, sessions, + received and sent bytes in a particular stream server zone. + operationId: deleteStreamServerZoneStat + responses: + '204': + description: Success + '404': + description: | + Server zone not found (*ServerZoneNotFound*), + [stream](https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream) + not configured (*StreamNotConfigured*) + schema: + $ref: '#/definitions/NginxError' + /stream/upstreams/: + get: + tags: + - Stream Upstreams + - Method GET + summary: | + Return status of all stream upstream server groups + description: | + Returns status of each stream upstream server group + and its servers. + operationId: getStreamUpstreams + produces: + - application/json + parameters: + - name: fields + in: query + type: string + description: | + Limits which fields of upstream server groups will be output. + If the “<literal>fields</literal>” value is empty, + only names of upstreams are output. + responses: + '200': + description: Success + schema: + $ref: '#/definitions/NginxStreamUpstreamMap' + '404': + description: | + [stream](https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream) + not configured (*StreamNotConfigured*) + schema: + $ref: '#/definitions/NginxError' + '/stream/upstreams/{streamUpstreamName}/': + parameters: + - name: streamUpstreamName + in: path + description: | + The name of a stream upstream server group. + required: true + type: string + get: + tags: + - Stream Upstreams + - Method GET + summary: | + Return status of a stream upstream server group + description: | + Returns status of a particular stream upstream server group + and its servers. + operationId: getStreamUpstream + produces: + - application/json + parameters: + - name: fields + in: query + type: string + description: | + Limits which fields of the upstream server group will be output. + responses: + '200': + description: Success + schema: + $ref: '#/definitions/NginxStreamUpstream' + '400': + description: | + Upstream is static (*UpstreamStatic*) + schema: + $ref: '#/definitions/NginxError' + '404': + description: | + Upstream not found (*UpstreamNotFound*), + [stream](https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream) + not configured (*StreamNotConfigured*) + schema: + $ref: '#/definitions/NginxError' + delete: + tags: + - Stream Upstreams + - Method DELETE + summary: | + Reset statistics of a stream upstream server group + description: | + Resets the statistics for each upstream server + in an upstream server group. + operationId: deleteStreamUpstreamStat + produces: + - application/json + responses: + '204': + description: Success + '400': + description: | + Upstream is static (*UpstreamStatic*) + schema: + $ref: '#/definitions/NginxError' + '404': + description: | + Upstream not found (*UpstreamNotFound*), + [stream](https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream) + not configured (*StreamNotConfigured*) + schema: + $ref: '#/definitions/NginxError' + '/stream/upstreams/{streamUpstreamName}/servers/': + parameters: + - name: streamUpstreamName + in: path + description: | + The name of an upstream server group. + required: true + type: string + get: + tags: + - Stream Upstreams + - Method GET + summary: | + Return configuration of all servers in a stream upstream server group + description: | + Returns configuration of each server + in a particular stream upstream server group. + operationId: getStreamUpstreamServers + produces: + - application/json + responses: + '200': + description: Success + schema: + $ref: '#/definitions/NginxStreamUpstreamConfServerMap' + '400': + description: | + Upstream is static (*UpstreamStatic*) + schema: + $ref: '#/definitions/NginxError' + '404': + description: | + Upstream not found (*UpstreamNotFound*), + [stream](https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream) + not configured (*StreamNotConfigured*) + schema: + $ref: '#/definitions/NginxError' + post: + tags: + - Stream Upstreams + - Method POST + summary: | + Add a server to a stream upstream server group + description: | + Adds a new server to a stream upstream server group. + Server parameters are specified in the JSON format. + operationId: postStreamUpstreamServer + produces: + - application/json + parameters: + - in: body + name: postStreamUpstreamServer + description: | + Address of a new server and other optional parameters + in the JSON format. + The “*ID*”, “*backup*”, and “*service*” parameters + cannot be changed. + required: true + schema: + $ref: '#/definitions/NginxStreamUpstreamConfServer' + responses: + '201': + description: Created + schema: + $ref: '#/definitions/NginxStreamUpstreamConfServer' + '400': + description: | + Upstream is static (*UpstreamStatic*), + invalid “**parameter**” value (*UpstreamConfFormatError*), + missing “*server*” argument (*UpstreamConfFormatError*), + unknown parameter “**name**” (*UpstreamConfFormatError*), + nested object or list (*UpstreamConfFormatError*), + “*error*” while parsing (*UpstreamBadAddress*), + no port in server “*host*” (*UpstreamBadAddress*), + service upstream “*host*” may not have port (*UpstreamBadAddress*), + service upstream “*host*” requires domain name (*UpstreamBadAddress*), + invalid “*weight*” (*UpstreamBadWeight*), + invalid “*max_conns*” (*UpstreamBadMaxConns*), + invalid “*max_fails*” (*UpstreamBadMaxFails*), + invalid “*fail_timeout*” (*UpstreamBadFailTimeout*), + invalid “*slow_start*” (*UpstreamBadSlowStart*), + “*service*” is empty (*UpstreamBadService*), + no resolver defined to resolve (*UpstreamConfNoResolver*), + upstream “**name**” has no backup (*UpstreamNoBackup*), + upstream “**name**” memory exhausted (*UpstreamOutOfMemory*) + schema: + $ref: '#/definitions/NginxError' + '404': + description: | + Upstream not found (*UpstreamNotFound*), + [stream](https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream) + not configured (*StreamNotConfigured*) + schema: + $ref: '#/definitions/NginxError' + '415': + description: JSON error (*JsonError*) + schema: + $ref: '#/definitions/NginxError' + '/stream/upstreams/{streamUpstreamName}/servers/{streamUpstreamServerId}': + parameters: + - name: streamUpstreamName + in: path + description: | + The name of the upstream server group. + required: true + type: string + - name: streamUpstreamServerId + in: path + description: | + The ID of the server. + required: true + type: string + get: + tags: + - Stream Upstreams + - Method GET + summary: | + Return configuration of a server in a stream upstream server group + description: | + Returns configuration of a particular server + in the stream upstream server group. + operationId: getStreamUpstreamServer + produces: + - application/json + responses: + '200': + description: Success + schema: + $ref: '#/definitions/NginxStreamUpstreamConfServer' + '400': + description: | + Upstream is static (*UpstreamStatic*), + invalid server ID (*UpstreamBadServerId*) + schema: + $ref: '#/definitions/NginxError' + '404': + description: | + Upstream not found (*UpstreamNotFound*), + server with ID “**id**” does not exist (*UpstreamServerNotFound*), + [stream](https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream) + not configured (*StreamNotConfigured*) + schema: + $ref: '#/definitions/NginxError' + patch: + tags: + - Stream Upstreams + - Method PATCH + summary: | + Modify a server in a stream upstream server group + description: | + Modifies settings of a particular server + in a stream upstream server group. + Server parameters are specified in the JSON format. + operationId: patchStreamUpstreamServer + produces: + - application/json + parameters: + - in: body + name: patchStreamUpstreamServer + description: | + Server parameters, specified in the JSON format. + The “*ID*”, “*backup*”, and “*service*” parameters + cannot be changed. + required: true + schema: + $ref: '#/definitions/NginxStreamUpstreamConfServer' + responses: + '200': + description: Success + schema: + $ref: '#/definitions/NginxStreamUpstreamConfServer' + '400': + description: | + Upstream is static (*UpstreamStatic*), + invalid “**parameter**” value (*UpstreamConfFormatError*), + unknown parameter “**name**” (*UpstreamConfFormatError*), + nested object or list (*UpstreamConfFormatError*), + “*error*” while parsing (*UpstreamBadAddress*), + invalid “*server*” argument (*UpstreamBadAddress*), + no port in server “*host*” (*UpstreamBadAddress*), + invalid server ID (*UpstreamBadServerId*), + invalid “*weight*” (*UpstreamBadWeight*), + invalid “*max_conns*” (*UpstreamBadMaxConns*), + invalid “*max_fails*” (*UpstreamBadMaxFails*), + invalid “*fail_timeout*” (*UpstreamBadFailTimeout*), + invalid “*slow_start*” (*UpstreamBadSlowStart*), + “*service*” is empty (*UpstreamBadService*), + server “**ID**” address is immutable (*UpstreamServerImmutable*), + server “**ID**” weight is immutable (*UpstreamServerWeightImmutable*), + upstream “*name*” memory exhausted (*UpstreamOutOfMemory*) + schema: + $ref: '#/definitions/NginxError' + '404': + description: | + Upstream not found (*UpstreamNotFound*), + server with ID “**id**” does not exist (*UpstreamServerNotFound*), + [stream](https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream) + not configured (*StreamNotConfigured*) + schema: + $ref: '#/definitions/NginxError' + '415': + description: JSON error (*JsonError*) + schema: + $ref: '#/definitions/NginxError' + delete: + tags: + - Stream Upstreams + - Method DELETE + summary: | + Remove a server from a stream upstream server group + description: | + Removes a server from a stream server group. + operationId: deleteStreamUpstreamServer + produces: + - application/json + responses: + '200': + description: Success + schema: + $ref: '#/definitions/NginxStreamUpstreamConfServerMap' + '400': + description: | + Upstream is static (*UpstreamStatic*), + invalid server ID (*UpstreamBadServerId*), + server “**id**” not removable (*UpstreamServerImmutable*) + schema: + $ref: '#/definitions/NginxError' + '404': + description: | + Upstream not found (*UpstreamNotFound*), + server with ID “**id**” does not exist (*UpstreamServerNotFound*), + [stream](https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream) + not configured (*StreamNotConfigured*) + schema: + $ref: '#/definitions/NginxError' +### +###DEFINITIONS +### +definitions: + ArrayOfStrings: + title: Array + description: | + An array of strings. + type: array + items: + type: string + NginxObject: + title: nginx + description: | + General information about nginx: + type: object + properties: + version: + type: string + description: | + Version of nginx. + build: + type: string + description: | + Name of nginx build. + address: + type: string + description: The address of the server that accepted status request. + generation: + type: integer + description: | + The total number of configuration + <a href="https://nginx.org/en/docs/control.html#reconfiguration">reloads</a>. + load_timestamp: + type: string + format: date-time + description: | + Time of the last reload of configuration, + in milliseconds since Epoch. + timestamp: + type: string + format: date-time + description: | + Current time in milliseconds since Epoch. + pid: + type: integer + description: | + The ID of the worker process that handled status request. + ppid: + type: integer + description: | + The ID of the master process that started the + <a href="https://nginx.org/en/docs/http/ngx_http_status_module.html#pid">worker process</a>. + example: + nginx: + version: 1.13.3 + build: nginx-plus-r12-p3 + address: 206.251.255.64 + generation: 2 + load_timestamp: 2017-07-07T11:09:21.594Z + timestamp: 2017-07-11T09:31:13.477Z + pid: 32212 + ppid: 32210 + NginxProcesses: + title: Processes + type: object + properties: + respawned: + type: integer + description: | + The total number of abnormally terminated + and respawned child processes. + example: + respawned: 0 + NginxConnections: + title: Connections + description: | + The number of accepted, dropped, active, and idle connections. + type: object + properties: + accepted: + type: integer + description: | + The total number of accepted client connections. + dropped: + type: integer + description: | + The total number of dropped client connections. + active: + type: integer + description: | + The current number of active client connections. + idle: + type: integer + description: | + The current number of idle client connections. + example: + accepted: 4968119 + dropped: 0 + active: 5 + idle: 117 + NginxSSLObject: + title: SSL + type: object + properties: + handshakes: + type: integer + description: | + The total number of successful SSL handshakes. + handshakes_failed: + type: integer + description: | + The total number of failed SSL handshakes. + session_reuses: + type: integer + description: | + The total number of session reuses during SSL handshake. + example: + handshakes: 79572 + handshakes_failed: 21025 + session_reuses: 15762 + NginxSlabZoneMap: + title: Slab Zones + description: | + Status zones that use slab allocator. + type: object + additionalProperties: + $ref: '#/definitions/NginxSlabZone' + example: + http_cache: + pages: + used: 2 + free: 2452 + slots: + 8: + used: 0 + free: 0 + reqs: 0 + fails: 0 + 16: + used: 0 + free: 0 + reqs: 0 + fails: 0 + 32: + used: 1 + free: 126 + reqs: 1 + fails: 0 + 64: + used: 2 + free: 62 + reqs: 2 + fails: 0 + 128: + used: 0 + free: 0 + reqs: 0 + fails: 0 + dns-backends: + pages: + used: 1143 + free: 2928 + slots: + 8: + used: 0 + free: 0 + reqs: 0 + fails: 0 + 16: + used: 0 + free: 0 + reqs: 0 + fails: 0 + 32: + used: 0 + free: 0 + reqs: 0 + fails: 0 + 64: + used: 1 + free: 63 + reqs: 1 + fails: 0 + 128: + used: 0 + free: 0 + reqs: 0 + fails: 0 + 256: + used: 18078 + free: 178 + reqs: 1635736 + fails: 0 + NginxSlabZone: + title: Shared memory zone with slab allocator + description: | + type: object + properties: + pages: + type: object + description: | + The number of free and used memory pages. + properties: + used: + type: integer + description: | + The current number of used memory pages. + free: + type: integer + description: | + The current number of free memory pages. + slots: + type: object + title: Memory Slots + description: | + Status data for memory slots (8, 16, 32, 64, 128, etc.) + additionalProperties: + $ref: '#/definitions/NginxSlabZoneSlot' + example: + pages: + used: 1143 + free: 2928 + slots: + 8: + used: 0 + free: 0 + reqs: 0 + fails: 0 + 16: + used: 0 + free: 0 + reqs: 0 + fails: 0 + 32: + used: 0 + free: 0 + reqs: 0 + fails: 0 + 64: + used: 1 + free: 63 + reqs: 1 + fails: 0 + 128: + used: 0 + free: 0 + reqs: 0 + fails: 0 + 256: + used: 18078 + free: 178 + reqs: 1635736 + fails: 0 + NginxSlabZoneSlot: + title: Memory Slot + type: object + properties: + used: + type: integer + description: | + The current number of used memory slots. + free: + type: integer + description: | + The current number of free memory slots. + reqs: + type: integer + description: | + The total number of attempts + to allocate memory of specified size. + fails: + type: integer + description: | + The number of unsuccessful attempts + to allocate memory of specified size. + NginxHTTPRequests: + title: HTTP Requests + type: object + properties: + total: + type: integer + description: | + The total number of client requests. + current: + type: integer + description: | + The current number of client requests. + example: + total: 10624511 + current: 4 + NginxHTTPServerZonesMap: + title: HTTP Server Zones + description: | + Status data for all HTTP + <a href="https://nginx.org/en/docs/http/ngx_http_status_module.html#status_zone">status zones</a>. + type: object + additionalProperties: + $ref: '#/definitions/NginxHTTPServerZone' + example: + site1: + processing: 2 + requests: 736395 + responses: + 1xx: 0 + 2xx: 727290 + 3xx: 4614 + 4xx: 934 + 5xx: 1535 + total: 734373 + discarded: 2020 + received: 180157219 + sent: 20183175459 + site2: + processing: 1 + requests: 185307 + responses: + 1xx: 0 + 2xx: 112674 + 3xx: 45383 + 4xx: 2504 + 5xx: 4419 + total: 164980 + discarded: 20326 + received: 51575327 + sent: 2983241510 + NginxHTTPServerZone: + title: HTTP Server Zone + type: object + properties: + processing: + type: integer + description: | + The number of client requests + that are currently being processed. + requests: + type: integer + description: | + The total number of client requests received from clients. + responses: + description: | + The total number of responses sent to clients and the + number of responses with status codes + “<code>1xx</code>”, “<code>2xx</code>”, “<code>3xx</code>”, + “<code>4xx</code>”, and “<code>5xx</code>”. + type: object + readOnly: true + properties: + 1xx: + type: integer + description: | + The number of responses with “<code>1xx</code>” status codes. + readOnly: true + 2xx: + type: integer + description: | + The number of responses with “<code>2xx</code>” status codes. + readOnly: true + 3xx: + type: integer + description: | + The number of responses with “<code>3xx</code>” status codes. + readOnly: true + 4xx: + type: integer + description: | + The number of responses with “<code>4xx</code>” status codes. + readOnly: true + 5xx: + type: integer + description: | + The number of responses with “<code>5xx</code>” status codes. + readOnly: true + total: + type: integer + description: The total number of responses sent to clients. + readOnly: true + discarded: + type: integer + description: | + The total number of + requests completed without sending a response. + received: + type: integer + description: | + The total number of bytes received from clients. + sent: + type: integer + description: | + The total number of bytes sent to clients. + example: + processing: 1 + requests: 706690 + responses: + 1xx: 0 + 2xx: 699482 + 3xx: 4522 + 4xx: 907 + 5xx: 266 + total: 705177 + discarded: 1513 + received: 172711587 + sent: 19415530115 + NginxHTTPCachesMap: + title: HTTP Caches + description: | + Status information of all HTTP caches configured by + <a href="https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_path">proxy_cache_path</a> + and other “<code>*_cache_path</code>” directives. + type: object + additionalProperties: + $ref: '#/definitions/NginxHTTPCache' + example: + http-cache: + size: 530915328 + max_size: 536870912 + cold: false + hit: + responses: 254032 + bytes: 6685627875 + stale: + responses: 0 + bytes: 0 + updating: + responses: 0 + bytes: 0 + revalidated: + responses: 0 + bytes: 0 + miss: + responses: 1619201 + bytes: 53841943822 + expired: + responses: 45859 + bytes: 1656847080 + responses_written: 44992 + bytes_written: 1641825173 + bypass: + responses: 200187 + bytes: 5510647548 + responses_written: 200173 + bytes_written: 44992 + frontend-cache: + size: 530915328 + max_size: 536870912 + cold: false + hit: + responses: 254032 + bytes: 6685627875 + stale: + responses: 0 + bytes: 0 + updating: + responses: 0 + bytes: 0 + revalidated: + responses: 0 + bytes: 0 + miss: + responses: 1619201 + bytes: 53841943822 + expired: + responses: 45859 + bytes: 1656847080 + responses_written: 44992 + bytes_written: 1641825173 + bypass: + responses: 200187 + bytes: 5510647548 + responses_written: 200173 + bytes_written: 44992 + NginxHTTPCache: + title: HTTP Cache + type: object + properties: + size: + type: integer + description: | + The current size of the cache. + max_size: + type: integer + description: | + The limit on the maximum size of the cache + specified in the configuration. + cold: + type: boolean + description: | + A boolean value indicating whether the “cache loader” process + is still loading data from disk into the cache. + hit: + type: object + properties: + responses: + type: integer + description: | + The total number of + <a href="https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_valid">valid</a> + responses read from the cache. + bytes: + type: integer + description: | + The total number of bytes read from the cache. + stale: + type: object + properties: + responses: + type: integer + description: | + The total number of expired responses read from the cache (see + <a href="https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_use_stale">proxy_cache_use_stale</a> + and other “<code>*_cache_use_stale</code>” directives). + bytes: + type: integer + description: The total number of bytes read from the cache. + updating: + type: object + properties: + responses: + type: integer + description: | + The total number of expired responses read from the cache + while responses were being updated (see + <a href="https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_use_stale_updating">proxy_cache_use_stale</a> + and other “<code>*_cache_use_stale</code>” directives). + bytes: + type: integer + description: | + The total number of bytes read from the cache. + revalidated: + type: object + properties: + responses: + type: integer + description: | + The total number of expired and revalidated responses + read from the cache (see + <a href="https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_revalidate">proxy_cache_revalidate</a> + and other “<code>*_cache_revalidate</code>” directives. + bytes: + type: integer + description: | + The total number of bytes read from the cache. + miss: + type: object + properties: + responses: + type: integer + description: | + The total number of responses not found in the cache. + bytes: + type: integer + description: | + The total number of bytes read from the proxied server. + responses_written: + type: integer + description: | + The total number of responses written to the cache. + bytes_written: + type: integer + description: | + The total number of bytes written to the cache. + expired: + type: object + properties: + responses: + type: integer + description: | + The total number of expired responses not taken from the cache. + bytes: + type: integer + description: | + The total number of bytes read from the proxied server. + responses_written: + type: integer + description: | + The total number of responses written to the cache. + bytes_written: + type: integer + description: | + The total number of bytes written to the cache. + bypass: + type: object + properties: + responses: + type: integer + description: | + The total number of responses not looked up in the cache due to the + <a href="https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_bypass">proxy_cache_bypass</a> + and other “<code>*_cache_bypass</code>” directives. + bytes: + type: integer + description: | + The total number of bytes read from the proxied server. + responses_written: + type: integer + description: | + The total number of responses written to the cache. + bytes_written: + type: integer + description: | + The total number of bytes written to the cache. + example: + size: 530915328 + max_size: 536870912 + cold: false + hit: + responses: 254032 + bytes: 6685627875 + stale: + responses: 0 + bytes: 0 + updating: + responses: 0 + bytes: 0 + revalidated: + responses: 0 + bytes: 0 + miss: + responses: 1619201 + bytes: 53841943822 + expired: + responses: 45859 + bytes: 1656847080 + responses_written: 44992 + bytes_written: 1641825173 + bypass: + responses: 200187 + bytes: 5510647548 + responses_written: 200173 + bytes_written: 44992 + NginxHTTPUpstreamMap: + title: HTTP Upstreams + description: | + Status information of all HTTP + <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#zone">dynamically configurable</a> + <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#upstream">groups</a>. + type: object + additionalProperties: + $ref: '#/definitions/NginxHTTPUpstream' + example: + trac-backend: + peers: + - id: 0 + server: 10.0.0.1:8088 + name: 10.0.0.1:8088 + backup: false + weight: 5 + state: up + active: 0 + requests: 667231 + header_time: 20 + response_time: 36 + responses: + 1xx: 0 + 2xx: 666310 + 3xx: 0 + 4xx: 915 + 5xx: 6 + total: 667231 + sent: 251946292 + received: 19222475454 + fails: 0 + unavail: 0 + health_checks: + checks: 26214 + fails: 0 + unhealthy: 0 + last_passed: true + downtime: 0 + downstart: 2017-07-07T11:09:21.602Z + selected: 2017-07-17T15:01:25Z + - id: 1 + server: 10.0.0.1:8089 + name: 10.0.0.1:8089 + backup: true + weight: 1 + state: unhealthy + active: 0 + requests: 0 + responses: + 1xx: 0 + 2xx: 0 + 3xx: 0 + 4xx: 0 + 5xx: 0 + total: 0 + sent: 0 + received: 0 + fails: 0 + unavail: 0 + health_checks: + checks: 26284 + fails: 26284 + unhealthy: 1 + last_passed: false + downtime: 262925617 + downstart: 2017-07-07T11:09:21.602Z + selected: 2017-07-17T15:01:25Z + keepalive: 0 + zombies: 0 + zone: trac-backend + hg-backend: + peers: + - id: 0 + server: 10.0.0.1:8088 + name: 10.0.0.1:8088 + backup: false + weight: 5 + state: up + active: 0 + requests: 667231 + header_time: 20 + response_time: 36 + responses: + 1xx: 0 + 2xx: 666310 + 3xx: 0 + 4xx: 915 + 5xx: 6 + total: 667231 + sent: 251946292 + received: 19222475454 + fails: 0 + unavail: 0 + health_checks: + checks: 26214 + fails: 0 + unhealthy: 0 + last_passed: true + downtime: 0 + downstart: 2017-07-07T11:09:21.602Z + selected: 2017-07-17T15:01:25Z + - id: 1 + server: 10.0.0.1:8089 + name: 10.0.0.1:8089 + backup: true + weight: 1 + state: unhealthy + active: 0 + requests: 0 + responses: + 1xx: 0 + 2xx: 0 + 3xx: 0 + 4xx: 0 + 5xx: 0 + total: 0 + sent: 0 + received: 0 + fails: 0 + unavail: 0 + health_checks: + checks: 26284 + fails: 26284 + unhealthy: 1 + last_passed: false + downtime: 262925617 + downstart: 2017-07-07T11:09:21.602Z + selected: 2017-07-17T15:01:25Z + keepalive: 0 + zombies: 0 + zone: hg-backend + NginxHTTPUpstream: + title: HTTP Upstream + type: object + properties: + peers: + $ref: '#/definitions/NginxHTTPUpstreamPeerMap' + keepalive: + type: integer + description: | + The current number of idle + <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive">keepalive</a> + connections. + zombies: + type: integer + description: | + The current number of servers removed + from the group but still processing active client requests. + zone: + type: string + description: | + The name of the shared memory + <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#zone">zone</a> + that keeps the group’s configuration and run-time state. + queue: + type: object + description: | + For the requests + <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#queue">queue</a>, + the following data are provided: + properties: + size: + type: integer + description: | + The current number of requests in the queue. + max_size: + type: integer + description: | + The maximum number of requests that can be in the queue + at the same time. + overflows: + type: integer + description: | + The total number of requests rejected due to the queue overflow. + example: + upstream_backend: + peers: + - id: 0 + server: 10.0.0.1:8088 + name: 10.0.0.1:8088 + backup: false + weight: 5 + state: up + active: 0 + max_conns: 20 + requests: 667231 + header_time: 20 + response_time: 36 + responses: + 1xx: 0 + 2xx: 666310 + 3xx: 0 + 4xx: 915 + 5xx: 6 + total: 667231 + sent: 251946292 + received: 19222475454 + fails: 0 + unavail: 0 + health_checks: + checks: 26214 + fails: 0 + unhealthy: 0 + last_passed: true + downtime: 0 + downstart: 2017-07-07T11:09:21.602Z + selected: 2017-07-17T15:01:25Z + - id: 1 + server: 10.0.0.1:8089 + name: 10.0.0.1:8089 + backup: true + weight: 1 + state: unhealthy + active: 0 + max_conns: 20 + requests: 0 + responses: + 1xx: 0 + 2xx: 0 + 3xx: 0 + 4xx: 0 + 5xx: 0 + total: 0 + sent: 0 + received: 0 + fails: 0 + unavail: 0 + health_checks: + checks: 26284 + fails: 26284 + unhealthy: 1 + last_passed: false + downtime: 262925617 + downstart: 2017-07-07T11:09:21.602Z + selected: 2017-07-17T15:01:25Z + keepalive: 0 + zombies: 0 + zone: upstream_backend + NginxHTTPUpstreamPeerMap: + title: HTTP Upstream Servers + description: | + An array of HTTP + <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#upstream">upstream servers</a>. + type: array + items: + $ref: '#/definitions/NginxHTTPUpstreamPeer' + NginxHTTPUpstreamPeer: + title: HTTP Upstream Server + type: object + properties: + id: + type: integer + description: The ID of the server. + readOnly: true + server: + type: string + description: | + An <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#server">address</a> + of the server. + service: + type: string + description: | + The + <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#service">service</a> + parameter value of the + <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#server">server</a> + directive. + name: + type: string + description: | + The name of the server specified in the + <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#server">server</a> + directive. + readOnly: true + backup: + type: boolean + description: | + A boolean value indicating whether the server is a + <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#backup">backup</a> + server. + weight: + type: integer + description: | + <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#weight">Weight</a> + of the server. + state: + type: string + enum: + - up + - draining + - down + - unavail + - checking + - unhealthy + description: | + Current state, which may be one of + “<code>up</code>”, “<code>draining</code>”, “<code>down</code>”, + “<code>unavail</code>”, “<code>checking</code>”, + and “<code>unhealthy</code>”. + active: + type: integer + description: | + The current number of active connections. + readOnly: true + max_conns: + type: integer + description: | + The + <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#max_conns">max_conns</a> + limit for the server. + requests: + type: integer + description: | + The total number of client requests forwarded to this server. + readOnly: true + responses: + type: object + readOnly: true + properties: + 1xx: + type: integer + description: | + The number of responses with “<code>1xx</code>” status codes. + readOnly: true + 2xx: + type: integer + description: | + The number of responses with “<code>2xx</code>” status codes. + readOnly: true + 3xx: + type: integer + description: | + The number of responses with “<code>3xx</code>” status codes. + readOnly: true + 4xx: + type: integer + description: | + The number of responses with “<code>4xx</code>” status codes. + readOnly: true + 5xx: + type: integer + description: | + The number of responses with “<code>5xx</code>” status codes. + readOnly: true + total: + type: integer + description: The total number of responses obtained from this server. + readOnly: true + sent: + type: integer + description: | + The total number of bytes sent to this server. + readOnly: true + received: + type: integer + description: | + The total number of bytes received from this server. + readOnly: true + fails: + type: integer + description: | + The total number of unsuccessful attempts + to communicate with the server. + readOnly: true + unavail: + type: integer + description: | + How many times the server became unavailable for client requests + (state “<code>unavail</code>”) due to the number of unsuccessful + attempts reaching the + <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#max_fails">max_fails</a> + threshold. + readOnly: true + health_checks: + type: object + readOnly: true + properties: + checks: + type: integer + description: | + The total number of + <a href="https://nginx.org/en/docs/http/ngx_http_upstream_hc_module.html#health_check">health check</a> + requests made. + fails: + type: integer + description: The number of failed health checks. + unhealthy: + type: integer + description: | + How many times the server became unhealthy + (state “<code>unhealthy</code>”). + last_passed: + type: boolean + description: | + Boolean indicating if the last health check request was successful + and passed + <a href="https://nginx.org/en/docs/http/ngx_http_upstream_hc_module.html#match">tests</a>. + downtime: + type: integer + readOnly: true + description: | + Total time the server was in the “<code>unavail</code>”, + “<code>checking</code>”, and “<code>unhealthy</code>” states. + downstart: + type: string + format: date-time + readOnly: true + description: | + The time (in milliseconds since Epoch) when the server became + “<code>unavail</code>”, “<code>checking</code>”, + or “<code>unhealthy</code>”. + selected: + type: string + format: date-time + readOnly: true + description: | + The time (in milliseconds since Epoch) + when the server was last selected to process a request. + header_time: + type: integer + readOnly: true + description: | + The average time to get the + <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#var_upstream_header_time">response header</a> + from the server. + response_time: + type: integer + readOnly: true + description: | + The average time to get the + <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#var_upstream_response_time">full response</a> + from the server. + NginxHTTPUpstreamConfServerMap: + title: HTTP Upstream Servers + description: | + An array of HTTP upstream servers for dynamic configuration. + type: array + items: + $ref: '#/definitions/NginxHTTPUpstreamConfServer' + example: + - id: 0 + server: 10.0.0.1:8088 + weight: 1 + max_conns: 0 + max_fails: 0 + fail_timeout: 10s + slow_start: 10s + route: '' + backup: false + down: false + - id: 1 + server: 10.0.0.1:8089 + weight: 4 + max_conns: 0 + max_fails: 0 + fail_timeout: 10s + slow_start: 10s + route: '' + backup: true + down: true + NginxHTTPUpstreamConfServer: + title: HTTP Upstream Server + description: | + Dynamically configurable parameters of an HTTP upstream + <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#server">server</a>: + type: object + properties: + id: + type: integer + description: | + The ID of the HTTP upstream server. + The ID is assigned automatically and cannot be changed. + readOnly: true + server: + type: string + description: | + Same as the + <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#address">address</a> + parameter of the HTTP upstream server. + When adding a server, it is possible to specify it as a domain name. + In this case, changes of the IP addresses + that correspond to a domain name will be monitored and automatically + applied to the upstream configuration + without the need of restarting nginx. + This requires the + <a href="https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver">resolver</a> + directive in the “<code>http</code>” block. + See also the + <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#resolve">resolve</a> + parameter of the HTTP upstream server. + service: + type: string + description: | + Same as the + <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#service">service</a> + parameter of the HTTP upstream server. + This parameter cannot be changed. + readOnly: true + weight: + type: integer + description: | + Same as the + <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#weight">weight</a> + parameter of the HTTP upstream server. + max_conns: + type: integer + description: | + Same as the + <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#max_conns">max_conns</a> + parameter of the HTTP upstream server. + max_fails: + type: integer + description: | + Same as the + <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#max_fails">max_fails</a> + parameter of the HTTP upstream server. + fail_timeout: + type: integer + description: | + Same as the + <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#fail_timeout">fail_timeout</a> + parameter of the HTTP upstream server. + slow_start: + type: integer + description: | + Same as the + <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#slow_start">slow_start</a> + parameter of the HTTP upstream server. + route: + type: string + description: | + Same as the + <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#route">route</a> + parameter of the HTTP upstream server. + backup: + type: boolean + description: | + When <code>true</code>, adds a + <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#backup">backup</a> + server. + This parameter cannot be changed. + readOnly: true + down: + type: boolean + description: | + Same as the + <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#down">down</a> + parameter of the HTTP upstream server. + parent: + type: string + description: | + Parent server ID of the resolved server. + The ID is assigned automatically and cannot be changed. + readOnly: true + host: + type: string + description: | + Hostname of the resolved server. + The hostname is assigned automatically and cannot be changed. + readOnly: true + drain: + type: string + description: | + Puts the HTTP upstream server into the “draining” mode. + In this mode, only requests + <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#sticky">bound</a> + to the server will be proxied to it. + The parameter cannot be initially set, + it can only be changed with the <code>PATCH</code> method. + example: + id: 1 + server: 10.0.0.1:8089 + weight: 4 + max_conns: 0 + max_fails: 0 + fail_timeout: 10s + slow_start: 10s + route: '' + backup: true + down: true + NginxHTTPKeyvalZonesMap: + title: Keyval Shared Memory Zones + description: | + Contents of all keyval shared memory zones. + type: object + additionalProperties: + $ref: '#/definitions/NginxHTTPKeyvalZone' + example: + keyval_zone: + key1: value1 + key2: value2 + key3: value3 + one: + arg1: value1 + arg2: value2 + arg3: value3 + NginxHTTPKeyvalZone: + title: Keyval Shared Memory Zone + description: | + Contents of a keyval shared memory zone. + type: object + example: + key1: value1 + key2: value2 + key3: value3 + NginxStreamServerZonesMap: + title: Stream Server Zones + description: | + Status information for all stream + <a href="https://nginx.org/en/docs/http/ngx_http_status_module.html#status_zone">status zones</a>. + type: object + additionalProperties: + $ref: '#/definitions/NginxStreamServerZone' + example: + mysql-frontend: + processing: 2 + connections: 270925 + sessions: + 2xx: 155564 + 4xx: 0 + 5xx: 0 + total: 270925 + discarded: 0 + received: 28988975 + sent: 3879346317 + dns: + processing: 1 + connections: 155569 + sessions: + 2xx: 155564 + 4xx: 0 + 5xx: 0 + total: 155569 + discarded: 0 + received: 4200363 + sent: 20489184 + NginxStreamServerZone: + title: Stream Server Zone + type: object + properties: + processing: + type: integer + description: | + The number of client connections + that are currently being processed. + connections: + type: integer + description: | + The total number of connections accepted from clients. + sessions: + type: object + description: | + Total number of completed sessions, + and the number of sessions completed with status codes + “<code>2xx</code>”, “<code>4xx</code>”, or “<code>5xx</code>”. + properties: + 2xx: + type: integer + description: | + The total number of sessions completed with + <a href="https://nginx.org/en/docs/stream/ngx_stream_core_module.html#var_status">status codes</a> + “<code>2xx</code>”. + 4xx: + type: integer + description: | + The total number of sessions completed with + <a href="https://nginx.org/en/docs/stream/ngx_stream_core_module.html#var_status">status codes</a> + “<code>4xx</code>”. + 5xx: + type: integer + description: | + The total number of sessions completed with + <a href="https://nginx.org/en/docs/stream/ngx_stream_core_module.html#var_status">status codes</a> + “<code>5xx</code>”. + total: + type: integer + description: The total number of completed client sessions. + discarded: + type: integer + description: | + The total number of + connections completed without creating a session. + received: + type: integer + description: The total number of bytes received from clients. + sent: + type: integer + description: The total number of bytes sent to clients. + example: + dns: + processing: 1 + connections: 155569 + sessions: + 2xx: 155564 + 4xx: 0 + 5xx: 0 + total: 155569 + discarded: 0 + received: 4200363 + sent: 20489184 + NginxStreamUpstreamMap: + title: Stream Upstreams + description: Status information of stream upstream server groups. + type: object + additionalProperties: + $ref: '#/definitions/NginxStreamUpstream' + example: + mysql_backends: + peers: + - id: 0 + server: 10.0.0.1:12345 + name: 10.0.0.1:12345 + backup: false + weight: 5 + state: up + active: 0 + max_conns: 30 + connecions: 1231 + sent: 251946292 + received: 19222475454 + fails: 0 + unavail: 0 + health_checks: + checks: 26214 + fails: 0 + unhealthy: 0 + last_passed: true + downtime: 0 + downstart: 2017-07-07T11:09:21.602Z + selected: 2017-07-17T15:01:25Z + - id: 1 + server: 10.0.0.1:12346 + name: 10.0.0.1:12346 + backup: true + weight: 1 + state: unhealthy + active: 0 + max_conns: 30 + connections: 0 + sent: 0 + received: 0 + fails: 0 + unavail: 0 + health_checks: + checks: 26284 + fails: 26284 + unhealthy: 1 + last_passed: false + downtime: 262925617 + downstart: 2017-07-07T11:09:21.602Z + selected: 2017-07-17T15:01:25Z + zombies: 0 + zone: mysql_backends + dns: + peers: + - id: 0 + server: 10.0.0.1:12347 + name: 10.0.0.1:12347 + backup: false + weight: 5 + state: up + active: 0 + max_conns: 30 + connections: 667231 + sent: 251946292 + received: 19222475454 + fails: 0 + unavail: 0 + health_checks: + checks: 26214 + fails: 0 + unhealthy: 0 + last_passed: true + downtime: 0 + downstart: 2017-07-07T11:09:21.602Z + selected: 2017-07-17T15:01:25Z + - id: 1 + server: 10.0.0.1:12348 + name: 10.0.0.1:12348 + backup: true + weight: 1 + state: unhealthy + active: 0 + connections: 0 + max_conns: 30 + sent: 0 + received: 0 + fails: 0 + unavail: 0 + health_checks: + checks: 26284 + fails: 26284 + unhealthy: 1 + last_passed: false + downtime: 262925617 + downstart: 2017-07-07T11:09:21.602Z + selected: 2017-07-17T15:01:25Z + zombies: 0 + zone: dns + NginxStreamUpstream: + title: Stream Upstream + type: object + properties: + peers: + $ref: '#/definitions/NginxStreamUpstreamPeerMap' + zombies: + type: integer + description: | + The current number of servers removed from the group + but still processing active client connections. + zone: + type: string + description: | + The name of the shared memory + <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#zone">zone</a> + that keeps the group’s configuration and run-time state. + example: + dns: + peers: + - id: 0 + server: 10.0.0.1:12347 + name: 10.0.0.1:12347 + backup: false + weight: 5 + state: up + active: 0 + max_conns: 50 + connections: 667231 + sent: 251946292 + received: 19222475454 + fails: 0 + unavail: 0 + health_checks: + checks: 26214 + fails: 0 + unhealthy: 0 + last_passed: true + downtime: 0 + downstart: 2017-07-07T11:09:21.602Z + selected: 2017-07-17T15:01:25Z + - id: 1 + server: 10.0.0.1:12348 + name: 10.0.0.1:12348 + backup: true + weight: 1 + state: unhealthy + active: 0 + max_conns: 50 + connections: 0 + sent: 0 + received: 0 + fails: 0 + unavail: 0 + health_checks: + checks: 26284 + fails: 26284 + unhealthy: 1 + last_passed: false + downtime: 262925617 + downstart: 2017-07-07T11:09:21.602Z + selected: 2017-07-17T15:01:25Z + zombies: 0 + zone: dns + NginxStreamUpstreamPeerMap: + title: Stream Upstream Servers + description: Array of stream upstream servers. + type: array + items: + $ref: '#/definitions/NginxStreamUpstreamPeer' + NginxStreamUpstreamPeer: + title: Stream Upstream Server + type: object + properties: + id: + type: integer + description: | + The ID of the server. + readOnly: true + server: + type: string + description: | + An + <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#server">address</a> + of the server. + service: + type: string + description: | + The + <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#service">service</a> + parameter value of the + <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#server">server</a> + directive. + name: + type: string + format: hostname + description: | + The name of the server specified in the + <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#server">server</a> + directive. + readOnly: true + backup: + type: boolean + description: | + A boolean value indicating whether the server is a + <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#backup">backup</a> + server. + weight: + type: integer + description: | + <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#weight">Weight</a> + of the server. + state: + type: string + readOnly: true + enum: + - up + - down + - unavail + - checking + - unhealthy + description: | + Current state, which may be one of + “<code>up</code>”, “<code>down</code>”, “<code>unavail</code>”, + “<code>checking</code>”, or “<code>unhealthy</code>”. + active: + type: integer + description: The current number of connections. + readOnly: true + max_conns: + type: integer + description: | + The + <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#max_conns">max_conns</a> + limit for the server. + connections: + type: integer + description: | + The total number of client connections forwarded to this server. + readOnly: true + connect_time: + type: integer + description: The average time to connect to the upstream server. + readOnly: true + first_byte_time: + type: integer + description: The average time to receive the first byte of data. + readOnly: true + response_time: + type: integer + description: The average time to receive the last byte of data. + readOnly: true + sent: + type: integer + description: The total number of bytes sent to this server. + readOnly: true + received: + type: integer + description: | + The total number of bytes received from this server. + readOnly: true + fails: + type: integer + description: | + The total number of unsuccessful attempts + to communicate with the server. + readOnly: true + unavail: + type: integer + description: | + How many times the server became unavailable for client connections + (state “<code>unavail</code>”) due to the number of unsuccessful + attempts reaching the + <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#max_fails">max_fails</a> + threshold. + readOnly: true + health_checks: + type: object + description: | + readOnly: true + properties: + checks: + type: integer + description: | + The total number of + <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_hc_module.html#health_check">health check</a> + requests made. + readOnly: true + fails: + type: integer + description: The number of failed health checks. + readOnly: true + unhealthy: + type: integer + description: | + How many times the server became unhealthy + (state “<code>unhealthy</code>”). + readOnly: true + last_passed: + type: boolean + description: | + Boolean indicating whether the last health check request + was successful and passed + <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_hc_module.html#match">tests</a>. + readOnly: true + downtime: + type: integer + description: | + Total time the server was in the + “<code>unavail</code>”, “<code>checking</code>”, + and “<code>unhealthy</code>” states. + readOnly: true + downstart: + type: string + format: date-time + description: | + The time (in milliseconds since Epoch) when the server became + “<code>unavail</code>”, “<code>checking</code>”, + or “<code>unhealthy</code>”. + readOnly: true + selected: + type: string + format: date-time + description: | + The time (in milliseconds since Epoch) + when the server was last selected to process a connection. + readOnly: true + NginxStreamUpstreamConfServerMap: + title: Stream Upstream Servers + description: | + An array of stream upstream servers for dynamic configuration. + type: array + items: + $ref: '#/definitions/NginxStreamUpstreamConfServer' + example: + - id: 0 + server: 10.0.0.1:12348 + weight: 1 + max_conns: 0 + max_fails: 1 + fail_timeout: 10s + slow_start: 0 + backup: false + down: false + - id: 1 + server: 10.0.0.1:12349 + weight: 1 + max_conns: 0 + max_fails: 1 + fail_timeout: 10s + slow_start: 0 + backup: false + down: false + NginxStreamUpstreamConfServer: + title: Stream Upstream Server + description: | + Dynamically configurable parameters of a stream upstream + <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#server">server</a>: + type: object + properties: + id: + type: integer + description: | + The ID of the stream upstream server. + The ID is assigned automatically and cannot be changed. + readOnly: true + server: + type: string + description: | + Same as the + <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#server">address</a> + parameter of the stream upstream server. + When adding a server, it is possible to specify it as a domain name. + In this case, changes of the IP addresses + that correspond to a domain name will be monitored and automatically + applied to the upstream configuration + without the need of restarting nginx. + This requires the + <a href="https://nginx.org/en/docs/stream/ngx_stream_core_module.html#resolver">resolver</a> + directive in the “<code>stream</code>” block. + See also the + <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#resolve">resolve</a> + parameter of the stream upstream server. + service: + type: string + description: | + Same as the + <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#service">service</a> + parameter of the stream upstream server. + This parameter cannot be changed. + readOnly: true + weight: + type: integer + description: | + Same as the + <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#weight">weight</a> + parameter of the stream upstream server. + max_conns: + type: integer + description: | + Same as the + <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#max_conns">max_conns</a> + parameter of the stream upstream server. + max_fails: + type: integer + description: | + Same as the + <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#max_fails">max_fails</a> + parameter of the stream upstream server. + fail_timeout: + type: integer + description: | + Same as the + <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#fail_timeout">fail_timeout</a> + parameter of the stream upstream server. + slow_start: + type: integer + description: | + Same as the + <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#slow_start">slow_start</a> + parameter of the stream upstream server. + backup: + type: boolean + description: | + When <code>true</code>, adds a + <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#backup">backup</a> + server. + This parameter cannot be changed. + readOnly: true + down: + type: boolean + description: | + Same as the + <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#down">down</a> + parameter of the stream upstream server. + parent: + type: string + description: | + Parent server ID of the resolved server. + The ID is assigned automatically and cannot be changed. + readOnly: true + host: + type: string + description: | + Hostname of the resolved server. + The hostname is assigned automatically and cannot be changed. + readOnly: true + example: + id: 0 + server: 10.0.0.1:12348 + weight: 1 + max_conns: 0 + max_fails: 1 + fail_timeout: 10s + slow_start: 0 + backup: false + down: false + NginxError: + title: Error + description: | + nginx error object. + type: object + properties: + path: + type: string + description: | + API path. + method: + type: string + description: | + HTTP method. + error: + type: object + properties: + status: + type: string + description: | + HTTP error code. + text: + type: string + description: | + Error description. + code: + type: string + description: | + Internal nginx error code. + request_id: + type: string + description: | + The ID of the request, equals the value of the + <a href="https://nginx.org/en/docs/http/ngx_http_core_module.html#var_request_id">$request_id</a> + variable. + href: + type: string + description: | + Link to reference documentation.
new file mode 100755 --- /dev/null +++ b/yaml/yaml2xml.py @@ -0,0 +1,523 @@ +#!/usr/bin/env python + +# Copyright (C) Nginx, Inc. + +import sys, re, datetime + +from yaml import load, dump +from collections import OrderedDict + +try: + from yaml import CLoader as Loader, CDumper as Dumper, resolver as resolver + +except ImportError: + from yaml import Loader, Dumper, resolver + + +# primitive markdown parser and utf encoding for output +def node_description(node): + + text = node.get('description') + if text == None: + return "" + + # + t = re.sub('\<code\>', r'<literal>', text) + t = re.sub('\</code\>', r'</literal>', t) + + t = re.sub('\<i\>', r'<value>', t) + t = re.sub('\</i\>', r'</value>', t) + + t = re.sub('\<a href=\"(.*)\"\>(.*)\</a\>', r'<link url="\1">\2</link>', t) + + # [desc](url) + t = re.sub('\[(.*)\]\((.*)\)', r'<link url="\2">\1</link>', t) + + # ** foo ** is value + t = re.sub('[*?][*?](\w+)[*?][*?]', r'<value>\1</value>', t) + + # * foo * is literal + t = re.sub('[*?](\w+)[*?]', r'<literal>\1</literal>', t) + + + return t.encode('utf-8').rstrip() + + +def pretty_endpoint(ep): + return ep.replace('/',' ').replace('_',' ') + + +# human-readable html element id based on path +def path_to_id(path): + if path == '/': + return 'root' + + str = path.replace('/', '_') + str = str.replace('{', '') + str = str.replace('}','') + + return uncamelcase(str[1:]) + + +def multiple(str): + fin2 = str[-2:] + fin = str[-1:] + + if fin2 == 's' or fin2 == 'sh' or fin2 == 'ch': + last = 'es' + elif fin == 'x' or fin == 'z': + last = 'es' + else: + last = 's' + + return str + last + +def uncamelcase(name): + s1 = re.sub('(.)([A-Z][a-z]+)', r'\1_\2', name) + return re.sub('([a-z0-9])([A-Z])', r'\1_\2', s1).lower() + +def make_defid(str): + return 'def_' + uncamelcase(str) + +# returns name of a referenced object +def get_refname(obj): + return obj['$ref'][14:] # remove '#/definitions/' + + +# returns referenced object itself from global definitions table +def node_from_ref(doc, obj): + return doc['definitions'][get_refname(obj)] + + +def render_doc(doc): + + out = "<section id=\"endpoints\" name=\"Endpoints\">\n" + out += render_paths(doc) + out += "</section>\n" + + # dry run, perform refcount + render_defs(doc) + + out += "<section id=\"definitions\" name=\"Response Objects\">\n" + out += render_defs(doc) + out += "</section>\n" + + return out + + +def render_paths(doc): + + global curr_endpoint + + paths = doc['paths'] + + out = "<para>\n" + out += "<list type=\"tag\">\n" + + for path_key in paths: + path_id = path_to_id(path_key) + curr_endpoint = path_key + out += render_path(doc, path_key, paths[path_key], path_id) + + curr_endpoint = None + + out += "</list>\n" + out += "</para>\n" + + return out + + +def render_defs(doc): + + out = "<para>\n" + out += "<list type=\"bullet\">\n" + + for d in doc['definitions']: + + if refs.get(d) == None: + continue + + node = doc['definitions'][d] + + out += "<listitem id=\"%s\">\n" % make_defid(d) + title = node.get('title', '') + + out += "<para>%s:</para>\n" % title + + out += render_node(doc, d, node, True) + + out += "</listitem>\n" + + out += "</list>\n" + out += "</para>\n" + + return out + + +def render_path(doc, path_key, path, path_id): + + out = "<tag-name id=\"%s\" name=\"%s\">\n" % (path_id, path_key) + out += "<literal>%s</literal>\n" % path_key + out += "</tag-name>\n" + + out += "<tag-desc>\n" + + # List of common method parameters + for method_key in path: + if method_key != 'parameters': + continue + + out += "Parameters common for all methods:\n" + out += render_parameters(doc, path[method_key]) + + + # List of methods for this path + out += '<para>Supported methods:</para>\n' + out += '<list type="bullet" compact="yes">\n' + + + for method_key in ['get', 'post', 'patch', 'delete']: + + if path.get(method_key) == None: + continue + + method = path[method_key] + + id = method['operationId'] + summ = method['summary'] + desc = node_description(method) + name = method_key.upper() + + out += "<listitem id=\"%s\">\n" % id + out += "<literal>%s</literal> - %s\n" % (name, summ) + out += "<para>%s</para>\n" % desc + + out += render_method(doc, name, method) + + out += "</listitem>\n" + + out += "</list>\n" + out += "</tag-desc>\n" + + return out + + +def render_method(doc, method_name, method): + + out = "" + + if method.get('parameters'): + out += "<para>\n" + out += "Request parameters:\n" + out += render_parameters(doc, method['parameters']) + out += "</para>\n" + + out += "<para>\n" + out += "Possible responses:\n" + out += "</para>\n" + + out += "<list type=\"bullet\">\n" + + for response_key in method['responses']: + out += "<listitem>" + out += render_response(doc, response_key, method['responses'][response_key]) + out += "</listitem>\n" + + out += "</list>\n" + + return out + + +def render_parameters(doc, params): + + out = '<list type="tag">\n' + + for p in params: + + out += "<tag-name><literal>%s</literal>\n" % p['name'] + out += "(" + + out += render_node(doc, None, p, True) + + if p.get("required"): + + if p["required"] == True: + out += ", required" + else: + out += ", optional" + else: + out += ", optional" + + out += ")" + + out += "</tag-name>\n" + out += "<tag-desc>\n" + + desc = node_description(p) + out += desc + + out += "</tag-desc>\n" + + out += "</list>\n" + + return out + + +def render_response(doc, response_key, response): + + out = "" + + desc = node_description(response) + + out += response_key + " - " + desc + + if response.get('schema'): + out += ", returns " + out += render_node(doc, None, response) + + return out + + + +def render_reference(doc, nodename, node): + + global in_array, refs + + out = "" + + ref = get_refname(node) + + refnode = node_from_ref(doc, node) + + if refnode.get('additionalProperties'): + # in entries + + out += "a collection of " + ref = get_refname(refnode['additionalProperties']) + target = node_from_ref(doc, refnode['additionalProperties']) + label = target.get('title', ref) + out += "\"<link id=\"%s\">%s</link>\"" % (make_defid(ref), label) + out += " objects" + refs[ref] = 1 + if curr_endpoint != None: + out += " for all %s" % pretty_endpoint(curr_endpoint) + + return out + + # arrays and primitive types are printed immediately + nt = refnode.get('type', 'object') + title = refnode.get('title', ref) + if nt == 'object': + if in_array == True: + title = multiple(title) + + out += "<link id=\"%s\">%s</link>" % (make_defid(ref), title) + refs[ref] = 1 + + elif nt == 'array': + + if nodename == 'peers': + ref = get_refname(refnode['items']) + out += "An array of:" + refnode = node_from_ref(doc, refnode['items']) + out += render_node(doc, ref, refnode, True) + return out + + out += "an array of " + + in_array = True + out += render_node(doc, nodename, refnode['items'], True) + in_array = False + else: + # dead code actually + out += "<literal>%s</literal>\n" % nt + + return out + + +# displays object recursively if described inline, or generates links +def render_node(doc, nodename, node, show_type=False): + + if node.get('$ref'): + return render_reference(doc, nodename, node) + + elif node.get('schema'): + return render_reference(doc, nodename, node['schema']) + + out = "" + + if node.get('additionalProperties'): + # in definitions + ref = get_refname(node['additionalProperties']) + target = node_from_ref(doc, node['additionalProperties']) + label = target.get('title', ref) + desc = node_description(node) + out += "<para>%s</para><para>A collection of " % desc + out += "\"<link id=\"%s\">%s</link>\"" % (make_defid(ref), label) + refs[ref] = 1 + out += " objects</para>\n" + + return out + + nt = node.get('type', 'object') + + if nt == 'object': + out += render_object(doc, node) + + elif nt == 'array': + desc = node_description(node) + out += "<para>%s</para>\n" % desc + out += "array element type:\n" + out += render_node(doc, nodename, node['items'], True) + + else: + if show_type: + if in_array == True: + out += "%s" % multiple(node['type']) + else: + out += "<literal>%s</literal>" % node['type'] + + if node.get('example'): + out += render_example(node['example']) + + return out + +def json_simple_type(obj): + + if isinstance(obj, bool): + if obj == True: + return 'true' + else: + return 'false' + + elif isinstance(obj, str): + return '"' + obj + '"' + + elif isinstance(obj,datetime.datetime): + t = obj.strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3] + z = obj.strftime("Z%Z") + return '"' + t + z + '"' + + else: + return str(obj) + +def render_example(obj, level = 0): + + out = "" + + if level == 0: + if isinstance(obj, dict) or isinstance(obj, list): + out += "<para>Example:</para>\n" + else: + out += "Example: <literal>%s</literal>\n" % json_simple_type(obj) + return out + + out += "<example>\n" + + indent = ' ' * level + next_indent = ' ' * (level + 1) + + if isinstance(obj, dict): + out += '{\n' + i = 0 + last = len(obj) + for key in obj: + out += next_indent + '"' + str(key) + '" : ' + out += render_example(obj[key], level + 1) + if i != last - 1: + out += ',' + out += '\n' + i = i + 1 + out += indent + "}" + + elif isinstance(obj, list): + out += '[\n' + i = 0 + last = len(obj) + for item in obj: + out += next_indent + out += render_example(item, level + 1) + if i != last - 1: + out += ',' + out += '\n' + i = i + 1 + out += indent + "]" + else: + out += json_simple_type(obj) + + if level == 0: + out += "</example>\n" + + + return out + + +def render_object(doc, obj): + + out = "" + + if obj.get('description'): + desc = node_description(obj) + out += desc + + if obj.get('properties') == None: + return out + + out += '<list type="tag">\n' + for p in obj['properties']: + + prop = obj['properties'][p] + + out += "<tag-name>\n" + out += "<literal>%s</literal>" % p + + if prop.get('properties') or prop.get('type') == 'object': + obj_type = None # there is nested object + else: + if prop.get('type'): + obj_type = prop['type'] # basic type + else: + obj_type = None # there is a reference + + if obj_type != None: + out += " (<literal>%s</literal>)\n" % obj_type + + out += "</tag-name>\n" + out += "<tag-desc>\n" + + if prop.get('description') and obj_type != None: + desc = node_description(prop) + out += desc + '\n' + + out += render_node(doc, p, prop) + + out += "</tag-desc>\n" + out += "</list>\n" + + return out + + +############################################################################### + +if len(sys.argv) < 2: + print("Usage: %s <nginx_api.yaml>" % sys.argv[0]) + sys.exit(1) + +refs = dict() +curr_endpoint = None +in_array = False + +def ordered_load(stream, Loader=Loader, object_pairs_hook=OrderedDict): + class OrderedLoader(Loader): + pass + def construct_mapping(loader, node): + loader.flatten_mapping(node) + return object_pairs_hook(loader.construct_pairs(node)) + OrderedLoader.add_constructor( + resolver.BaseResolver.DEFAULT_MAPPING_TAG,construct_mapping) + return load(stream, OrderedLoader) + +with open(sys.argv[1], 'r') as src: + content = src.read() + doc = ordered_load(content, Loader=Loader) + print(render_doc(doc))