loopbackio / loopbackio/loopback-next

Overriding title in `getModelSchemaRef` causes duplication in OpenAPI schema

Open
#5,645 8 comments 0 reactions 0 assignees View on GitHub
bug help wanted
Dominant language
TypeScript
Stars
5.1k
Forks
1.1k
Avg merge
2d 21h
Merged PRs (30d)
27

Description

## Steps to reproduce

Define a controller with `getModelSchemaRef(SomeModel, {title: 'TitleOverride'})`.

Controller definition

```typescript
export class UserController {
@post('/users', {
security: OPERATION_SECURITY_SPEC,
responses: {
'200': {
description: 'User',
content: {
'application/json': {
schema: {
'x-ts-type': User,
},
},
},
},
},
})
async create(
@requestBody({
content: {
'application/json': {
schema: getModelSchemaRef(NewUserRequest, {
title: 'NewUser',
}),
},
},
})
newUserRequest: NewUserRequest,
): Promise {
// implementation
}
}
```

## Current Behavior

The controller above emits schema definitions for both `NewUserRequest` and `NewUser`. While `NewUserRequest` is not referenced anywhere else in the schema.

## Expected Behavior

Only `NewUser` is present in OpenAPI schema.

## Additional information

`@loopback/repository-json-schema@2.4.2`
`@loopback/openapi-v3@3.4.1`

I presume `NewUserRequest` is generated from `getModelSchemaRef` as it should while `NewUser` comes from parsing `paramTypes` where it causes a cache miss due to overridden `title`.

A probable fix could exclude a parameter corresponding to `requestBody` from enumeration here

https://github.com/strongloop/loopback-next/blob/7f8d8356946dc236dd4daecbfae12e0a0662cf1c/packages/openapi-v3/src/controller-spec.ts#L329

## Acceptance Criteria

- [ ] Don't generate unused schema for parameter decorated with `@requestBody`

A solution I can think of is:
https://github.com/strongloop/loopback-next/blob/7f8d8356946dc236dd4daecbfae12e0a0662cf1c/packages/openapi-v3/src/controller-spec.ts#L329

should search through the content objects in the request body spec, if all contents' schemas exist in reference, then skip generating the one inferred from model ctor.

Contributor guide

Open the contributing guide

Research direction

Start in packages/openapi-v3/src/controller-spec.ts around the referenced parameter enumeration and trace how requestBody schemas and inferred model constructors enter the OpenAPI components. Reproduce the title override case, then verify that a request body whose schema is already referenced does not generate an unused duplicate schema.

Written by the indexing model from the issue text.

Assessment

Tech stack
openapi, typescript
Domain
api, backend-api-design
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.