feat(openapi): migrate to openapi(sagger) 3.0 from 2.0

[dzmitry-lahoda]

Feature Request

Migrate openapi (swagger) generator to openapi 3.0

Use Case:

I am Rust develop. All rust developers develop crypto.

And have not time to develop process-compose like thing (all attempts stalled).

Also Go people are very experienced in process orchestration things

So it is reasonable to just use Process Compose from Rust via Open API.

But Rust crates which render idiomatic rust like progenitor and okapi work only with Open API 3+, not 2.

Proposed Change:

Use Go mod to generate 3.0 OpenAPI

Who Benefits From The Change(s)?

• All who use openapi 3.0, and cannot 2.0
• All who wants to migrate to 3.0 as it is strictly better and safes and more precise (better generated clients).

Alternative Approaches

• GRPC API (will fix better structured return schemas, not they are just objects)

• yaml first approach (will fix better structured return schemas, not they are just objects)

• convert v2 to v3 via https://github.com/getkin/kin-openapi (I am on it now, checking if it slick). UPDATE: it is not cmdcli, need to type Go code. tried https://converter.swagger.io/#/Converter/convertByContent and it converted to invalid output as (un)expected. UPDATE2: seems useless as can only produce untyped JSON in return

[dzmitry-lahoda]

Will donate 100 USD equivalent in crypto for this feature.

[dzmitry-lahoda]

Current generator seems tries to gen more valid swagger, but I do not see now next fields in master in json

// @title Process Compose API
// @version 1.0
// @description process compose description

[dzmitry-lahoda]

Seems gin swagger max is // @Produce json, so pretty useless open API.

Found only one OPI 3.0 for Go as of now, but it different http framwork, https://github.com/a-h/rest .

[dzmitry-lahoda]

@F1bonacc1 what do you think about these things?

[dzmitry-lahoda]

There are several approaches to generate Swagger from GRPC if that route is possible. I have seen some in Google Agones gameservers and Cosmos SDK blochchain repos (written in Go)

[F1bonacc1]

Hi @dzmitry-lahoda,

Can you provide a bit more information? What would be an acceptable result of this?

1. To have an always up-to-date swagger.json or swagger.yaml in OpenAPI 3 format here? Or
2. To have an OpenAPI 3 webApp on http://localhost:8080/? Or
3. Both.

If it's only 1, can you please confirm if this is what you are looking for:

OpenAPI 3

```json { "components": {}, "info": { "contact": { "name": "Eugene Berger", "url": "https://f1bonacc1.github.io/process-compose/" }, "description": "This is a sample server Process Compose server.", "license": { "name": "Apache 2.0", "url": "http://www.apache.org/licenses/LICENSE-2.0.html" }, "title": "Swagger Process Compose API", "version": "1.0" }, "openapi": "3.0.3", "paths": { "/hostname": { "get": { "description": "Get process compose hostname", "responses": { "200": { "description": "OK" } }, "summary": "Get Hostname", "tags": [ "Hostname" ] } }, "/live": { "get": { "description": "Check if server is responding", "responses": { "200": { "description": "OK" } }, "summary": "Liveness Check", "tags": [ "Liveness" ] } }, "/process": { "post": { "description": "Update porcess", "responses": { "200": { "description": "OK" } }, "summary": "Updates process configuration", "tags": [ "Process" ] } }, "/process/info/{name}": { "get": { "description": "Retrieves the given process and its config", "parameters": [ { "description": "Process Name", "in": "path", "name": "name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Process Config" } }, "summary": "Get process config", "tags": [ "Process" ] } }, "/process/logs/{name}/{endOffset}/{limit}": { "get": { "description": "Retrieves the process logs", "parameters": [ { "description": "Process Name", "in": "path", "name": "name", "required": true, "schema": { "type": "string" } }, { "description": "Offset from the end of the log", "in": "path", "name": "endOffset", "required": true, "schema": { "type": "integer" } }, { "description": "Limit of lines to get (0 will get all the lines till the end)", "in": "path", "name": "limit", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Process Logs" } }, "summary": "Get process logs", "tags": [ "Process" ] } }, "/process/ports/{name}": { "get": { "description": "Retrieves process open ports", "parameters": [ { "description": "Process Name", "in": "path", "name": "name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Process Ports" } }, "summary": "Get process ports", "tags": [ "Process" ] } }, "/process/restart/{name}": { "post": { "description": "Restarts the process", "parameters": [ { "description": "Process Name", "in": "path", "name": "name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "Restarted Process Name" } }, "summary": "Restart a process", "tags": [ "Process" ] } }, "/process/scale/{name}/{scale}": { "patch": { "description": "Scale a process", "parameters": [ { "description": "Process Name", "in": "path", "name": "name", "required": true, "schema": { "type": "string" } }, { "description": "New amount of process replicas", "in": "path", "name": "scale", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "Scaled Process Name" } }, "summary": "Scale a process to a given replicas count", "tags": [ "Process" ] } }, "/process/start/{name}": { "post": { "description": "Starts the process if the state is not 'running' or 'pending'", "parameters": [ { "description": "Process Name", "in": "path", "name": "name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "Started Process Name" } }, "summary": "Start a process", "tags": [ "Process" ] } }, "/process/stop/{name}": { "patch": { "description": "Sends kill signal to the process", "parameters": [ { "description": "Process Name", "in": "path", "name": "name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "Stopped Process Name" } }, "summary": "Stop a process", "tags": [ "Process" ] } }, "/process/{name}": { "get": { "description": "Retrieves the given process and its status", "parameters": [ { "description": "Process Name", "in": "path", "name": "name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Process State" } }, "summary": "Get process state", "tags": [ "Process" ] } }, "/processes": { "get": { "description": "Retrieves all the configured processes and their status", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Processes Status" } }, "summary": "Get all processes", "tags": [ "Process" ] } }, "/processes/stop": { "patch": { "description": "Sends kill signal to the processes list", "requestBody": { "content": { "*/*": { "schema": { "items": { "type": "string" }, "type": "array" } } }, "description": "Processes Names", "required": true, "x-originalParamName": "[]string" }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "Stopped Processes Names" } }, "summary": "Stop processes", "tags": [ "Process" ] } }, "/project": { "post": { "description": "Update running project", "responses": { "200": { "description": "OK" } }, "summary": "Updates running processes", "tags": [ "Project" ] } }, "/project/state": { "get": { "description": "Retrieves project state information", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Project State" } }, "summary": "Get project state", "tags": [ "Project" ] } }, "/project/stop": { "post": { "description": "Shuts down the server", "responses": { "200": { "description": "OK" } }, "summary": "Stops all the processes and the server", "tags": [ "Project" ] } } } } ```

If this is acceptable I will find an automated way to keep it up to date for each release.