From f9297fdd31899efd434a066193121462a0a1772f Mon Sep 17 00:00:00 2001 From: rollun-com Date: Sun, 19 Dec 2021 14:51:31 +0200 Subject: [PATCH 1/4] feat: init new docs --- new-docs/README.md | 47 ++++++++++++++++++++++++++++++++ new-docs/client/php.md | 1 + new-docs/client/ts.md | 1 + new-docs/server/php.md | 1 + new-docs/server/ts.md | 1 + new-docs/tools/openapi-lint.md | 1 + new-docs/tools/swagger-editor.md | 5 ++++ 7 files changed, 57 insertions(+) create mode 100644 new-docs/README.md create mode 100644 new-docs/client/php.md create mode 100644 new-docs/client/ts.md create mode 100644 new-docs/server/php.md create mode 100644 new-docs/server/ts.md create mode 100644 new-docs/tools/openapi-lint.md create mode 100644 new-docs/tools/swagger-editor.md diff --git a/new-docs/README.md b/new-docs/README.md new file mode 100644 index 0000000..8487da7 --- /dev/null +++ b/new-docs/README.md @@ -0,0 +1,47 @@ +# OpenAPI Rollun + +This document describes how to work with OpenAPI in our company - +how to write manifests, generate code for both server side and client side. + +## Overview + +The OpenAPI Specification is a community-driven open specification within +the [OpenAPI Initiative](https://www.openapis.org/), a Linux Foundation Collaborative Project. + +We use OpenAPI to: +- follow API first approach +- make self documented APIs +- generate boilerplate code (api client, server stubs) + +Right now we support 3 platforms: +- PHP (server + client) +- TypeScript (server + client) + +## General workflow + +If there is a need for new service, workflow will be: +- Create OpenAPI spec, using our custom **(LINK TO SWAGGER EDITOR DOCS)** +- Generate code for server from OpenAPI spec (controllers, DTOs etc) **(LINK TO PHP/TS SERVER CODE GEN DOCS)** +- Add openapi lint to your CI/CD pipeline. **(LINK TO OPENAPI LINT DOCS)** +- Implement methods in service + +If you want to consume new service via defined OpenAPI: +- Generate client from OpenAPI spec **(LINK TO PHP/TS OPENAPI CLIENT CODE GEN)** + +## Tools + +### [Swagger Editor Docs](./tools/swagger-editor.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) + +## Demo + +**TODO: link to demo repository with examples of OpenAPI specs + generated servers/clients with instructions for each language** diff --git a/new-docs/client/php.md b/new-docs/client/php.md new file mode 100644 index 0000000..30404ce --- /dev/null +++ b/new-docs/client/php.md @@ -0,0 +1 @@ +TODO \ No newline at end of file diff --git a/new-docs/client/ts.md b/new-docs/client/ts.md new file mode 100644 index 0000000..30404ce --- /dev/null +++ b/new-docs/client/ts.md @@ -0,0 +1 @@ +TODO \ No newline at end of file diff --git a/new-docs/server/php.md b/new-docs/server/php.md new file mode 100644 index 0000000..30404ce --- /dev/null +++ b/new-docs/server/php.md @@ -0,0 +1 @@ +TODO \ No newline at end of file diff --git a/new-docs/server/ts.md b/new-docs/server/ts.md new file mode 100644 index 0000000..30404ce --- /dev/null +++ b/new-docs/server/ts.md @@ -0,0 +1 @@ +TODO \ No newline at end of file diff --git a/new-docs/tools/openapi-lint.md b/new-docs/tools/openapi-lint.md new file mode 100644 index 0000000..976ea51 --- /dev/null +++ b/new-docs/tools/openapi-lint.md @@ -0,0 +1 @@ +# OpenAPI lint \ No newline at end of file diff --git a/new-docs/tools/swagger-editor.md b/new-docs/tools/swagger-editor.md new file mode 100644 index 0000000..f08397f --- /dev/null +++ b/new-docs/tools/swagger-editor.md @@ -0,0 +1,5 @@ +# Swagger Editor + +**TODO: Swagger editor docs** + +**TODO: list of custom rules for OpenAPI specs** \ No newline at end of file From 6f867376098a2b1029f95b1a6bc6c718b03e3eee Mon Sep 17 00:00:00 2001 From: rollun-com Date: Sun, 19 Dec 2021 14:56:51 +0200 Subject: [PATCH 2/4] feat: add links --- new-docs/README.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/new-docs/README.md b/new-docs/README.md index 8487da7..2e7b008 100644 --- a/new-docs/README.md +++ b/new-docs/README.md @@ -20,17 +20,19 @@ Right now we support 3 platforms: ## General workflow If there is a need for new service, workflow will be: -- Create OpenAPI spec, using our custom **(LINK TO SWAGGER EDITOR DOCS)** -- Generate code for server from OpenAPI spec (controllers, DTOs etc) **(LINK TO PHP/TS SERVER CODE GEN DOCS)** -- Add openapi lint to your CI/CD pipeline. **(LINK TO OPENAPI LINT DOCS)** +- Create OpenAPI spec, using our custom [Swagger Editor](#swagger-editor-docs) +- Generate code for server from OpenAPI spec (controllers, DTOs etc) with [generator](#server-stub-generator) +- Add [openapi lint](#openapi-lint) to your CI/CD pipeline. - Implement methods in service If you want to consume new service via defined OpenAPI: -- Generate client from OpenAPI spec **(LINK TO PHP/TS OPENAPI CLIENT CODE GEN)** +- Generate client from OpenAPI spec with [generator](#client-lib-generator) ## Tools -### [Swagger Editor Docs](./tools/swagger-editor.md) +### Swagger Editor Docs - [doc](./tools/swagger-editor.md) + +### OpenAPI lint - [doc](./tools/openapi-lint.md) ### Server stub generator From f846522fe274762bea0de3f7ad9a620c47732b97 Mon Sep 17 00:00:00 2001 From: rollun-com Date: Sun, 19 Dec 2021 15:56:58 +0200 Subject: [PATCH 3/4] feat: transalte + contributing template --- new-docs/CONTRIBUTING.md | 35 ++++++++++++++++++++++++++++ new-docs/README.md | 42 +++++++++++++++++++--------------- new-docs/quick-start/README.md | 0 3 files changed, 59 insertions(+), 18 deletions(-) create mode 100644 new-docs/CONTRIBUTING.md create mode 100644 new-docs/quick-start/README.md diff --git a/new-docs/CONTRIBUTING.md b/new-docs/CONTRIBUTING.md new file mode 100644 index 0000000..1279834 --- /dev/null +++ b/new-docs/CONTRIBUTING.md @@ -0,0 +1,35 @@ +# (Название вашего предложения) + +1. Описание проблемы, которую решает предложение + примеры + +Описание: TODO + +2. Описание предлогаемых изменений + примеры + +Описание: TODO + +3. Являются ли изменения 'breaking'? Если да, что не совместимо. + +Ответ: TODO + +4. Есть ли возможность добавить поддержку в серверные генераторы? + +TS: Да/Нет
+PHP: Да/Нет + +5. Есть ли возможность добавить поддержку в клиентские генераторы? + +TS: Да/Нет
+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/Изменения не требуются diff --git a/new-docs/README.md b/new-docs/README.md index 2e7b008..7e5d78e 100644 --- a/new-docs/README.md +++ b/new-docs/README.md @@ -1,32 +1,37 @@ # OpenAPI Rollun -This document describes how to work with OpenAPI in our company - -how to write manifests, generate code for both server side and client side. +Этот документ описывает, как мы в компании работаем с OpenAPI +технологией, какие у нас есть инструменты и правила. ## Overview -The OpenAPI Specification is a community-driven open specification within -the [OpenAPI Initiative](https://www.openapis.org/), a Linux Foundation Collaborative Project. +The OpenAPI Specification - это открытая спецификация. Документацию проэкта можно +посмотреть тут - [OpenAPI Initiative a Linux Foundation Collaborative Project.](https://www.openapis.org/). -We use OpenAPI to: -- follow API first approach -- make self documented APIs -- generate boilerplate code (api client, server stubs) +Мы используем OpenAPI для: +- того что бы следовать API first approach +- разрабатывать самодокументируемые API +- генерировать шаблонный код (api client, server stubs) -Right now we support 3 platforms: +Мы поддерживаем 2 платформы: - PHP (server + client) - TypeScript (server + client) +## Contributing + +Для того, что бы предложить свои изменения, нужно открыть pull request и +заполнить [специальный шаблон](./CONTRIBUTING.md). + ## General workflow -If there is a need for new service, workflow will be: -- Create OpenAPI spec, using our custom [Swagger Editor](#swagger-editor-docs) -- Generate code for server from OpenAPI spec (controllers, DTOs etc) with [generator](#server-stub-generator) -- Add [openapi lint](#openapi-lint) to your CI/CD pipeline. -- Implement methods in service +Для того, что бы разрабоать новый сервер, нужно: +- Создать OpenAPI spec, используя наш модифицированный [Swagger Editor](#swagger-editor-docs) +- Сгенерировать код для сервера с OpenAPI spec (контроллеры, DTOs и тд.) с помощью [generator](#server-stub-generator) +- Добавить [openapi lint](#openapi-lint) в ваш CI/CD pipeline. +- Реализовать методы, в сгенерированом коде. -If you want to consume new service via defined OpenAPI: -- Generate client from OpenAPI spec with [generator](#client-lib-generator) +Для того, что бы начать работу с сервисом через его API, нужно: +- Сгенерировать с OpenAPI spec клиентскую библиотеку с помощью [generator](#client-lib-generator) ## Tools @@ -44,6 +49,7 @@ If you want to consume new service via defined OpenAPI: - PHP - [docs](./client/php.md) - TypeScript - [docs](./client/ts.md) -## Demo +## Quick Start -**TODO: link to demo repository with examples of OpenAPI specs + generated servers/clients with instructions for each language** +Гайд с примерами кода/команд, которые нужны для ефективной работы +с OpenAPI в нашей компании [link](./quick-start/README.md) diff --git a/new-docs/quick-start/README.md b/new-docs/quick-start/README.md new file mode 100644 index 0000000..e69de29 From b4c137e42001ef5afa11bb3f1062fff2d3962638 Mon Sep 17 00:00:00 2001 From: rollun-com Date: Sun, 19 Dec 2021 16:30:17 +0200 Subject: [PATCH 4/4] feat: issue + pr templates --- new-docs/README.md | 9 +- new-docs/issue-template.md | 136 +++++++++++++++++++ new-docs/{CONTRIBUTING.md => pr-template.md} | 4 +- 3 files changed, 145 insertions(+), 4 deletions(-) create mode 100644 new-docs/issue-template.md rename new-docs/{CONTRIBUTING.md => pr-template.md} (88%) diff --git a/new-docs/README.md b/new-docs/README.md index 7e5d78e..10d199f 100644 --- a/new-docs/README.md +++ b/new-docs/README.md @@ -19,8 +19,9 @@ The OpenAPI Specification - это открытая спецификация. Д ## Contributing -Для того, что бы предложить свои изменения, нужно открыть pull request и -заполнить [специальный шаблон](./CONTRIBUTING.md). +Изменения в спецификацию происходят в 2 этапа: +1. Открыть issue с описанием проблемы, и всем необходимым материалом. [шаблон](./issue-template.md) +2. Открыть pull request с описанием проблемы/ссылкой на issue, и всем необходимым материалом. [шаблон](./pr-template.md) ## General workflow @@ -53,3 +54,7 @@ The OpenAPI Specification - это открытая спецификация. Д Гайд с примерами кода/команд, которые нужны для ефективной работы с OpenAPI в нашей компании [link](./quick-start/README.md) + + ## Cross platform testing + +TODO: продумать механизм тестирования разных манифестов, для всех поддерживаемых платформ diff --git a/new-docs/issue-template.md b/new-docs/issue-template.md new file mode 100644 index 0000000..ad3f0ef --- /dev/null +++ b/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' +``` + diff --git a/new-docs/CONTRIBUTING.md b/new-docs/pr-template.md similarity index 88% rename from new-docs/CONTRIBUTING.md rename to new-docs/pr-template.md index 1279834..52dc523 100644 --- a/new-docs/CONTRIBUTING.md +++ b/new-docs/pr-template.md @@ -1,10 +1,10 @@ # (Название вашего предложения) -1. Описание проблемы, которую решает предложение + примеры +1. Описание проблемы, которую решает предложение + пример манифеста, который не работает Описание: TODO -2. Описание предлогаемых изменений + примеры +2. Описание предлогаемых изменений + пример манифеста, который должен работать Описание: TODO