diff --git a/README.md b/README.md
index 02a6ce5be2..084f620af4 100644
--- a/README.md
+++ b/README.md
@@ -1,27 +1,29 @@
-# The OpenAPI Specification
+# OpenAPI Спецификация (Русская редакция)
 [](https://www.codetriage.com/oai/openapi-specification)
-The OpenAPI Specification is a community-driven open specification within the [OpenAPI Initiative](https://www.openapis.org/), a Linux Foundation Collaborative Project.
+Спецификация OpenAPI - это открытая спецификация, поддерживаемая сообществом в рамках [Инициативы OpenAPI](https://www.openapis.org/), совместный проект с Linux Foundation.
-The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service.
+Относительно назначения, OpenAPI рассматривается как универсальный интерфейс для пользователей (клиентов) по взаимодействию с сервисами (серверами). Аналогичен описаниям интерфейса для программирования более низкого уровня. Если спроектирована спецификация для некоторого сервиса, то на её основании можно генерировать исходный код для библиотек клиентских приложений, текстовую документацию для пользователей, варианты тестирования и др. Для этих действий имеется большой набор инструментов для различных языков программирования и платформ.
-Use cases for machine-readable API definition documents include, but are not limited to: interactive documentation; code generation for documentation, clients, and servers; and automation of test cases. OpenAPI documents describe an APIs services and are represented in either YAML or JSON formats. These documents may either be produced and served statically or be generated dynamically from an application.
+OpenAPI представляет собой формализованную спецификацию и полноценный фреймворк для описания, создания, использования и визуализации веб-сервисов REST. Задачей является позволить клиентским системам и документации синхронизировать свои обновления с изменениями на сервере. Это достигается тем, что методы, параметры, модели и другие элементы посредством OpenAPI интегрируются с программным обеспечением сервера и всё время с ним синхронизируются
-The OpenAPI Specification does not require rewriting existing APIs. It does not require binding any software to a service – the service being described may not even be owned by the creator of its description. It does, however, require the capabilities of the service be described in the structure of the OpenAPI Specification. Not all services can be described by OpenAPI – this specification is not intended to cover every possible style of HTTP APIs, but does include support for [REST APIs](https://en.wikipedia.org/wiki/Representational_state_transfer). The OpenAPI Specification does not mandate a specific development process such as design-first or code-first. It does facilitate either technique by establishing clear interactions with a HTTP API.
+Документы OpenAPI описывают сервис API и представлены в форматах YAML или JSON. Эти документы могут либо создаваться и обслуживаться статически (FirstAPI), либо создаваться динамически из приложения (CodeFirst).
-This GitHub project is the starting point for OpenAPI. Here you will find the information you need about the OpenAPI Specification, simple examples of what it looks like, and some general information regarding the project.
+Спецификация OpenAPI не требует перезаписи существующих API. Это не требует привязки какого–либо программного обеспечения к сервису - описываемый сервис может даже не принадлежать создателю его описания. Однако требует, чтобы возможности сервиса были описаны в структуре спецификации OpenAPI. Не все службы могут быть описаны с помощью OpenAPI – эта спецификация не предназначена для охвата всех возможных вариантов API HTTP, но включает поддержку [API REST](https://en.wikipedia.org/wiki/Representational_state_transfer). Спецификация OpenAPI не предписывает конкретный процесс разработки, такой как сначала описание (First-API, Design-First) или сначала код (Code-First).
-## Current Version - 3.1.0
+Этот GitHub проект может является отправной точкой для OpenAPI. Здесь вы найдете необходимую информацию об спецификации OpenAPI, простые примеры того, как она выглядит, и некоторую общую информацию о проекте, на русском языке.
-The current version of the OpenAPI specification is [OpenAPI Specification 3.1.0](versions/3.1.0.md).
+## Текущая версия - 3.1.0
-### Previous Versions
+Текущая версия OpenAPI спецификации [OpenAPI Specification 3.1.0](versions/3.1.0.md).
-This repository also contains all [previous versions](versions).
+### Предыдущая версия
+
+Этот репозиторий так же содержит все [предыдущие версии](versions).
Each folder in this repository, such as [examples](examples) and [schemas](schemas), should contain folders pertaining to the current and previous versions of the specification.
@@ -29,12 +31,12 @@ Each folder in this repository, such as [examples](examples) and [schemas](schem
If you just want to see it work, check out the [list of current examples](examples).
-## Tools and Libraries
+## Инструменты и библиотеки
Looking to see how you can create your own OpenAPI definition, present it, or otherwise use it? Check out the growing
[list of implementations](IMPLEMENTATIONS.md).
-## Participation
+## Участие
The current process for development of the OpenAPI Specification is described in
[Development Guidelines](DEVELOPMENT.md).
@@ -52,8 +54,6 @@ The OpenAPI Initiative encourages participation from individuals and companies a
Not all feedback can be accommodated and there may be solid arguments for or against a change being appropriate for the specification.
-## Licensing
-
-See: [License (Apache-2.0)](https://github.com/OAI/OpenAPI-Specification/blob/main/LICENSE)
+## Лицензия
-
+Смотрите: [License (Apache-2.0)](https://github.com/OAI/OpenAPI-Specification/blob/main/LICENSE)
diff --git a/versions/3.1.0.md b/versions/3.1.0.md
index 39425bd6b9..d54bab595b 100644
--- a/versions/3.1.0.md
+++ b/versions/3.1.0.md
@@ -1,18 +1,18 @@
-# OpenAPI Specification
+# OpenAPI Спецификация
-#### Version 3.1.0
+#### Версия 3.1.0
-The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [BCP 14](https://tools.ietf.org/html/bcp14) [RFC2119](https://tools.ietf.org/html/rfc2119) [RFC8174](https://tools.ietf.org/html/rfc8174) when, and only when, they appear in all capitals, as shown here.
+Ключевые слова "ДОЛЖЕН", "НЕ ДОЛЖЕН", "ТРЕБУЕТСЯ", "ДОЛЖЕН", "НЕ ДОЛЖЕН", "ДОЛЖЕН", "НЕ ДОЛЖЕН", "РЕКОМЕНДУЕТСЯ", "НЕ РЕКОМЕНДУЕТСЯ", "МОЖЕТ" и "НЕОБЯЗАТЕЛЬНО" встреченные в этом документе, следует понимать как они описаны в следующих рекомендациях [BCP 14](https://tools.ietf.org/html/bcp14) [RFC2119](https://tools.ietf.org/html/rfc2119) [RFC8174](https://tools.ietf.org/html/rfc8174).
-This document is licensed under [The Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0.html).
+Этот документ распостраняется под лицензией [The Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0.html).
-## Introduction
+## Вступление
-The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to HTTP APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic.
+OpenAPI Specification (с англ. — «OpenAPI Спецификация») (далее OAS) — формализованная спецификация и экосистема множества инструментов, предоставляющая интерфейс между front-end системами, кодом библиотек низкого уровня и коммерческими решениями в виде API. Вместе с тем, cпецификация построена таким образом, что не зависит от языков программирования, и удобна в использовании как человеком, так и машиной.
-An OpenAPI definition can then be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools, and many other use cases.
+Относительно назначения, OpenAPI рассматривается как универсальный интерфейс для пользователей (клиентов) по взаимодействию с сервисами (серверами). Если спроектирована спецификация для некоторого сервиса, то на её основании можно генерировать исходный код для библиотек клиентских приложений, текстовую документацию для пользователей, варианты тестирования и др. Для этих действий имеется большой набор инструментов для различных языков программирования и платформ.
-## Table of Contents
+## Содержание
- [Definitions](#definitions)
@@ -66,7 +66,7 @@ An OpenAPI definition can then be used by documentation generation tools to disp
-## Definitions
+## Определения
##### OpenAPI Document
A self-contained or composite resource which defines or describes an API or elements of an API. The OpenAPI document MUST contain at least one [paths](#pathsObject) field, a [components](#oasComponents) field or a [webhooks](#oasWebhooks) field. An OpenAPI document uses and conforms to the OpenAPI Specification.
@@ -95,13 +95,13 @@ Some examples of possible media type definitions:
application/vnd.github.v3.diff
application/vnd.github.v3.patch
```
-##### HTTP Status Codes
+##### HTTP коды статусов ответа (HTTP Status Codes)
The HTTP Status Codes are used to indicate the status of the executed operation.
The available status codes are defined by [RFC7231](https://tools.ietf.org/html/rfc7231#section-6) and registered status codes are listed in the [IANA Status Code Registry](https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml).
-## Specification
+## Спецификация
-### Versions
+### Версии
The OpenAPI Specification is versioned using a `major`.`minor`.`patch` versioning scheme. The `major`.`minor` portion of the version string (for example `3.1`) SHALL designate the OAS feature set. *`.patch`* versions address errors in, or provide clarifications to, this document, not the feature set. Tooling which supports OAS 3.1 SHOULD be compatible with all OAS 3.1.\* versions. The patch version SHOULD NOT be considered by tooling, making no distinction between `3.1.0` and `3.1.1` for example.
@@ -109,7 +109,7 @@ Occasionally, non-backwards compatible changes may be made in `minor` versions o
An OpenAPI document compatible with OAS 3.\*.\* contains a required [`openapi`](#oasVersion) field which designates the version of the OAS that it uses.
-### Format
+### Формат
An OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format.
@@ -134,13 +134,13 @@ In order to preserve the ability to round-trip between YAML and JSON formats, YA
**Note:** While APIs may be defined by OpenAPI documents in either YAML or JSON format, the API request and response bodies and other content are not required to be JSON or YAML.
-### Document Structure
+### Структура документа
An OpenAPI document MAY be made up of a single document or be divided into multiple, connected parts at the discretion of the author. In the latter case, [`Reference Objects`](#referenceObject) and [`Schema Object`](#schemaObject) `$ref` keywords are used.
It is RECOMMENDED that the root OpenAPI document be named: `openapi.json` or `openapi.yaml`.
-### Data Types
+### Типы данных
Data types in the OAS are based on the types supported by the [JSON Schema Specification Draft 2020-12](https://tools.ietf.org/html/draft-bhutton-json-schema-00#section-4.2.1).
Note that `integer` as a type is also supported and is defined as a JSON number without a fraction or exponent part.
@@ -173,22 +173,22 @@ If a URI contains a fragment identifier, then the fragment should be resolved pe
Relative references in [`Schema Objects`](#schemaObject), including any that appear as `$id` values, use the nearest parent `$id` as a Base URI, as described by [JSON Schema Specification Draft 2020-12](https://tools.ietf.org/html/draft-bhutton-json-schema-00#section-8.2). If no parent schema contains an `$id`, then the Base URI MUST be determined according to [RFC3986](https://tools.ietf.org/html/rfc3986#section-5.1).
-### Relative References in URLs
+### Относительные ссылки в URL-адресах
Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-4.2).
Unless specified otherwise, relative references are resolved using the URLs defined in the [`Server Object`](#serverObject) as a Base URL. Note that these themselves MAY be relative to the referring document.
-### Schema
+### Схема
In the following description, if a field is not explicitly **REQUIRED** or described with a MUST or SHALL, it can be considered OPTIONAL.
-#### OpenAPI Object
+#### OpenAPI Объект
This is the root object of the [OpenAPI document](#oasDocument).
-##### Fixed Fields
+##### Фиксированные (зарезервированные) поля
-Field Name | Type | Description
+Имя поля | Тип | Описание
---|:---:|---
openapi | `string` | **REQUIRED**. This string MUST be the [version number](#versions) of the OpenAPI Specification that the OpenAPI document uses. The `openapi` field SHOULD be used by tooling to interpret the OpenAPI document. This is *not* related to the API [`info.version`](#infoVersion) string.
info | [Info Object](#infoObject) | **REQUIRED**. Provides metadata about the API. The metadata MAY be used by tooling as required.
@@ -224,7 +224,7 @@ Field Name | Type | Description
This object MAY be extended with [Specification Extensions](#specificationExtensions).
-##### Info Object Example
+##### Пример хранения информации о спецификации (Info Object)
```json
{
@@ -260,7 +260,7 @@ license:
version: 1.0.1
```
-#### Contact Object
+#### Контактная информация (Contact Object)
Contact information for the exposed API.
@@ -290,13 +290,13 @@ url: https://www.example.com/support
email: support@example.com
```
-#### License Object
+#### Информация о лицензии (License Object)
License information for the exposed API.
-##### Fixed Fields
+##### Фиксированные (зарезервированные) поля
-Field Name | Type | Description
+Имя поля | Тип | Описание
---|:---:|---
name | `string` | **REQUIRED**. The license name used for the API.
identifier | `string` | An [SPDX](https://spdx.org/spdx-specification-21-web-version#h.jxpfx0ykyb60) license expression for the API. The `identifier` field is mutually exclusive of the `url` field.
@@ -304,7 +304,7 @@ Field Name | Type | Description
This object MAY be extended with [Specification Extensions](#specificationExtensions).
-##### License Object Example
+##### Пример информация о лицензии (License Object)
```json
{
@@ -318,7 +318,7 @@ name: Apache 2.0
identifier: Apache-2.0
```
-#### Server Object
+#### Информация о серверах (Server Object)
An object representing a Server.
@@ -3447,9 +3447,9 @@ Two examples of this:
2. The [Path Item Object](#pathItemObject) MAY be empty. In this case, the viewer will be aware that the path exists, but will not be able to see any of its operations or parameters. This is different from hiding the path itself from the [Paths Object](#pathsObject), because the user will be aware of its existence. This allows the documentation provider to finely control what the viewer can see.
-## Appendix A: Revision History
+## Appendix A: История версий
-Version | Date | Notes
+Версия | Дата | Замечания
--- | --- | ---
3.1.0 | 2021-02-15 | Release of the OpenAPI Specification 3.1.0
3.1.0-rc1 | 2020-10-08 | rc1 of the 3.1 specification