feat: init new docs

new-docs/README.md

@@ -0,0 +1,60 @@
+# OpenAPI Rollun
+
+Этот документ описывает, как мы в компании работаем с OpenAPI
+технологией, какие у нас есть инструменты и правила.
+
+## Overview
+
+The OpenAPI Specification - это открытая спецификация. Документацию проэкта можно
+посмотреть тут - [OpenAPI Initiative a Linux Foundation Collaborative Project.](https://www.openapis.org/).
+
+Мы используем OpenAPI для:
+- того что бы следовать API first approach
+- разрабатывать самодокументируемые API
+- генерировать шаблонный код (api client, server stubs)
+
+Мы поддерживаем 2 платформы:
+- PHP (server + client)
+- TypeScript (server + client)
+
+## Contributing
+
+Изменения в спецификацию происходят в 2 этапа:
+1. Открыть issue с описанием проблемы, и всем необходимым материалом. [шаблон](./issue-template.md)
+2. Открыть pull request с описанием проблемы/ссылкой на issue, и всем необходимым материалом. [шаблон](./pr-template.md)
+
+## General workflow
+
+Для того, что бы разрабоать новый сервер, нужно:
+- Создать OpenAPI spec, используя наш модифицированный [Swagger Editor](#swagger-editor-docs)
+- Сгенерировать код для сервера с OpenAPI spec (контроллеры, DTOs и тд.) с помощью [generator](#server-stub-generator)
+- Добавить [openapi lint](#openapi-lint) в ваш CI/CD pipeline.
+- Реализовать методы, в сгенерированом коде.
+
+Для того, что бы начать работу с сервисом через его API, нужно:
+- Сгенерировать с OpenAPI spec клиентскую библиотеку с помощью [generator](#client-lib-generator)
+
+## Tools
+
+### Swagger Editor Docs - [doc](./tools/swagger-editor.md)
+
+### OpenAPI lint - [doc](./tools/openapi-lint.md)
+
+### Server stub generator
+
+- PHP - [docs](./server/php.md)
+- TypeScript - [docs](./server/ts.md)
+
+### Client Lib generator
+
+- PHP - [docs](./client/php.md)
+- TypeScript - [docs](./client/ts.md)
+
+## Quick Start
+
+Гайд с примерами кода/команд, которые нужны для ефективной работы
+с OpenAPI в нашей компании [link](./quick-start/README.md)
+
+ ## Cross platform testing
+
+TODO: продумать механизм тестирования разных манифестов, для всех поддерживаемых платформ

new-docs/client/php.md

@@ -0,0 +1 @@
+TODO

new-docs/client/ts.md

@@ -0,0 +1 @@
+TODO

new-docs/issue-template.md

@@ -0,0 +1,136 @@
+# (название проблемы)
+
+1. Описание проблемы
+
+Описание: TODO
+
+2. Пример манифеста, который не работает
+
+Шаблон манифеста - 
+```yaml
+openapi: 3.0.0
+info:
+  version: "1"
+  title: Sample
+  description: Sample manifest to showcase issue
+servers:
+  - url: http://server.dev/openapi/Sample/v1
+paths:
+  /{namespace}/Entity:
+    get:
+      parameters:
+        - in: query
+          name: "status"
+          required: false
+          schema:
+            type: string
+        - in: path
+          name: "namespace"
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: entity
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/EntityResult'
+        '400':
+          description: Bad Request
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResult'
+        '500':
+          description: Internal error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResult'
+    post:
+      parameters:
+        - in: path
+          name: "namespace"
+          required: true
+          schema:
+            type: string
+      requestBody:
+        description: ""
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Entity'
+      responses:
+        '201':
+          description: entity
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/EntityResult'
+        '400':
+          description: Bad Request
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResult'
+        '500':
+          description: Internal error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResult'
+components:
+  schemas:
+    Message:
+      type: object
+      required:
+        - level
+        - text
+      properties:
+        level:
+          type: string
+          description: 'Message level  (like in a logger)'
+          example: 'error'
+        text:
+          type: string
+          description: 'Message text'
+          example: 'Something wrong.'
+        context:
+          type: array
+          description: 'Message context (like in a logger)'
+          items:
+            type: string
+    ErrorResult:
+      type: object
+      properties:
+        messages:
+          type: array
+          items:
+            $ref: '#/components/schemas/Message'
+    Result:
+      allOf:
+        - $ref: '#/components/schemas/ErrorResult'
+      type: object
+      properties:
+        data:
+          type: object
+    EntityResult:
+      allOf:
+        - $ref: '#/components/schemas/Result'
+      type: object
+      properties:
+        data:
+          $ref: '#/components/schemas/Entity'
+    Entity:
+      type: object
+      required:
+        - id
+        - name
+      properties:
+        id:
+          type: string
+          example: '5f51f78ccaa4c'
+```
+

new-docs/pr-template.md

@@ -0,0 +1,35 @@
+# (Название вашего предложения)
+
+1. Описание проблемы, которую решает предложение + пример манифеста, который не работает
+
+Описание: TODO
+
+2. Описание предлогаемых изменений + пример манифеста, который должен работать
+
+Описание: TODO
+
+3. Являются ли изменения 'breaking'? Если да, что не совместимо.
+
+Ответ: TODO
+
+4. Есть ли возможность добавить поддержку в серверные генераторы?
+
+TS: Да/Нет<br>
+PHP: Да/Нет
+
+5. Есть ли возможность добавить поддержку в клиентские генераторы?
+
+TS: Да/Нет<br>
+PHP: Да/Нет
+
+6. Есть ли возможность добавить поддержку в Swagger editor?
+
+Да/Нет
+
+7. Обновить документацию нужных модулей. 
+- генератор php server - PR link/Изменения не требуются
+- генератор php client - PR link/Изменения не требуются
+- генератор ts server - PR link/Изменения не требуются
+- генератор ts client - PR link/Изменения не требуются
+- генератор swagger editor - PR link/Изменения не требуются
+- quick start - PR link/Изменения не требуются

new-docs/server/php.md

@@ -0,0 +1 @@
+TODO

new-docs/server/ts.md

@@ -0,0 +1 @@
+TODO

new-docs/tools/openapi-lint.md

@@ -0,0 +1 @@
+# OpenAPI lint

new-docs/tools/swagger-editor.md

@@ -0,0 +1,5 @@
+# Swagger Editor
+
+**TODO: Swagger editor docs**
+
+**TODO: list of custom rules for OpenAPI specs**