Unable to Explore API (generated OpenAPI spec is not valid)

[Vandivier]

Description / Steps to reproduce / Feature proposal

1. lb4 example, then pick the Todo app.
2. install it and get it running.
3. visit http://localhost:3000/openapi.yaml
4. paste the yaml within http://editor.swagger.io

Current Behavior

get errors:

Expected Behavior

don't get errors :)

[virkt25]

Able to reproduce. Looks like we aren't generating responses property and a few other issues possibly from JSON to YAML conversion. Great catch!

[dhmlau]

There are 2 kinds of errors when opening our generated openapi.json in editor.swagger.io:

1. responses object is empty

   • According to the spec (https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#response-object), at least description should exist.
   • A quick change for users (to just get rid of the error) is to modify responses: {} to:

   responses: {
        "200": {
          description: "some description"
        }
      }
   

2. If in field in the parameter object is path, the following needs to exist:

required: true

i.e. 

 parameters:
     - name: id
       in: path
       schema:
         type: string
       required: true 
 ```

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#parameter-object

 

[bajtos]

If in field in the parameter object is path, the following needs to exist:
required: true

I am proposing to modify our @param.path.* decorators to always set required: true. See packages/openapi-v3/src/decorators/parameter.decorator.ts.

[bajtos]

I am proposing to modify our @param.path.* decorators to always set required: true. See packages/openapi-v3/src/decorators/parameter.decorator.ts.

Never mind :) A different solution has been already landed via #1633 👍

[virkt25]

Acceptance Criteria

• Introduce a default responses object on the generated OpenAPI Spec (responses: {200: {description: ''}}
• Introduce a @responses decorator which takes in an OpenAPI responses object for a given controller method. This will take the exact spec. Should be able to resolve {schema: MODEL} to a model in the spec.
• Update CLI to automatically decorate CRUD APIs with @responses() decorator

---

The following will be moved to a new TASK.

• Introduce a @response decorator (must override base class to allow for multiple to be set on a controller method). This is a sugar method with a simplified UX.
  Example UX:

@response('returns a user') // auto-detect User Model
@response('confirmation of deleted instance', {type: object, schema: {status: boolean, count: number}})
@response(404, 'user not found', HttpErrors.NotFoundError)

[bajtos]

I am afraid I disagree with the acceptance criteria outlined in the comment above, please see #1655 (comment)

[bajtos]

The following will be moved to a new TASK: Introduce a @response decorator (must override base class to allow for multiple to be set on a controller method). This is a sugar method with a simplified UX.

@virkt25 could you please create that follow-up task and/or post a link the GH issue if it already exists?

[virkt25]

Follow up issue: #1672