search

hasura / graphql-engine

Blazing fast, instant realtime GraphQL APIs on your DB with fine grained access control, also trigger webhooks on database events.
https://hasura.io
Apache License 2.0
31.19k stars 2.77k forks source link

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

Open edmundmunday opened 3 years ago

edmundmunday commented 3 years ago

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

image

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.

iamkhalidbashir commented 1 year ago

same