Feature request: Enhancement for enum documentation

[Halynsky]

Enum is a very useful type. I like to use enums =)

The main goal of this request is to have more possibilities to show allowed values to my frontend developers. For now, in v1.0.0 I found one possibility to do it. And still, its need some additional code. It would be nice to have it out of the box and to have some more possibilities to show enum values.

So first of all what we have:

export enum SocketClientState {
    INIT = 'INIT',
    IDLE = 'IDLE',
    BATTLE = 'BATTLE',
    MENU = 'MENU',
    BACKGROUND = 'BACKGROUND'
}

@ApiModel( {
    description : "Model for update client state" ,
    name : "ClientInfoUpdate"
} )
export class ClientStateUpdate {
    @ApiModelProperty( {
        description : "New client state" ,
        required : true,
        enum : enumToArray(SocketClientState)
    } )
    state: SocketClientState = null;
}

@ApiOperationPatch({
    path: "/state",
    summary: "Updates state of connected websocket client",
    parameters: {
        body: { description: "New stat of client", required: true, model: "ClientInfoUpdate"}
    },
    responses: {}
})
@httpPatch("/state", AuthMiddleware)
private async updateState(@request() req: Request, @requestBody() body: ClientStateUpdate) {
    this.socketService.updateClientState(req.user.id, body.state)
}

So we have a useless wrapper for one value. But we have documented code. For me, it's less evil.

If I didn't find the right solution. Plz, feel free to correct me.

In Java version of Swagger documentation (Spring Fox), you even can select one of the enum values in the Swagger UI. It's very useful for testing and understanding of API. It would be also a very nice feature in your library.

So now solutions that could be nice for developers:

I don't have strong knowlage of JS and TS so its just theoretical proposals.

1 - Just send enum type into the parameter

@ApiModel( {
    description : "Model for update client state" ,
    name : "ClientInfoUpdate"
} )
export class ClientStateUpdate {
    @ApiModelProperty( {
        description : "New client state" ,
        required : true,
        enum : SocketClientState
    } )
    state: SocketClientState = null;
}

@ApiOperationPatch({
    path: "/state",
    summary: "Updates state of connected websocket client",
    parameters: {
        body: { description: "New stat of client", required: true, model: "ClientInfoUpdate"}
    },
    responses: {}
})
@httpPatch("/state", AuthMiddleware)
private async updateState(@request() req: Request, @requestBody() body: ClientStateUpdate) {
    this.socketService.updateClientState(req.user.id, body.state)
}

2 - Send enum into parameters property

    @ApiOperationPatch({
        path: "/state/{newState}",
        summary: "Updates state of connected websocket client",
        parameters: {
            path: { newState: {
                    description: "New stat of client", required: true, model: "SocketClientState"
                } }
        },
        responses: {}
    })
    @httpPatch("/state/:newState", AuthMiddleware)
    private async updateState1(@request() req: Request, @requestParam("newState") newState: SocketClientState) {
        this.socketService.updateClientState(req.user.id, newState)
    }

3- Set enum of model for entire body. When we have 1 parameter, JSON wrapper for it a little bit useless

    @ApiOperationPatch({
        path: "/state",
        summary: "Updates state of connected websocket client",
        parameters: {
            body: { description: "New stat of client", required: true, model: "SocketClientState"}
        },
        responses: {}
    })
    @httpPatch("/state", AuthMiddleware)
    private async updateState(@request() req: Request, @requestBody() body: SocketClientState) {
        this.socketService.updateClientState(req.user.id, body)
    }

4 - Integretion with inversify-express-utils. Invoide of duplicated code

5 - Dropdown selectors at UI when value is enum

Thank you for a nice library! =) Best regards!