hasura / hasura/graphql-engine

Auto-generated Swagger doc for REST is missing fields to make it a valid OpenAPI Spec

Open
#7,804 1 comment 0 reactions 0 assignees View on GitHub
k/bug RESTified
Dominant language
TypeScript
Stars
32.1k
Forks
3k
PR merge metrics
PR metrics pending

Description

### Version Information
Server Version: v2.1.0-beta.2
CLI Version (for CLI related issue):

### Environment

OSS

### What is the expected behaviour?

When retrieving an auto-generated Swagger doc for a REST endpoint,
It should generate a valid OpenAPI spec document and it should include at least a successful response object,
So that the generated OpenAPI Spec can be used in code-gen tools that consume these spec files without it needing to be significantly modified.

### Keywords

swagger, openapi, rest

### What is the current behaviour?

When generating a swagger document for a REST endpoint there are several things missing:
1. Paramaterized variables in URL paths are not marked as "required" in the spec. According to the standard, path params are always required (https://swagger.io/docs/specification/describing-parameters/#:~:text=Path-,Parameters,-Path%20parameters%20are)
2. All of the information for the responses are also missing. I would be expecting at least information for 200 and 4XX responses. - I would expect the 200 responses to include the properties returned by the GraphQL query to be listed in the response "schema", and it should show as either an array response or an object response.
- 400 responses ideally would also document the properties of the response object too.

### How to reproduce the issue?

1. Setup a REST endpoint in Hasura
2. Generate the swagger doc by visiting "/api/swagger/json"
3. Put that swagger doc json file into an OpenAPI spec editor. There will be several errors shown.

### Screenshots or Screencast

![image](https://user-images.githubusercontent.com/20222644/141257632-4eb8907e-e341-482f-9db1-d883816e6a06.png)

![image](https://user-images.githubusercontent.com/20222644/141257648-3768a5ad-1cf9-4b26-8c39-3344b0f7a920.png)

### Any possible solutions?

If a REST endpoint includes parameterized variables, mark them as required in the spec.

For the 200 responses for each REST endpoint, use the existing GraphQL schema to generate the required schema object in the Swagger document.

For the 4XX responses for each REST endpoint, just include a standard schema documenting the standard Hasura error json payload.

### Can you identify the location in the source code where the problem exists?

No idea sorry
### If the bug is confirmed, would you be willing to submit a PR?

Don't know how sorry.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.