client-cli: set response types to undefined for 204 responses, support 201 and empty objects

[gunjam]

Hi,

In #884 I added support for 204 responses with no body to the client plugin, the changes in this PR allow the client-cli to generate undefined types for those responses rather than throw because of a lack of a 200 response.

Example:

{
  "responses": {
    "204": {
      "description": "Delete an task template",
      "content": {
        "*/*": {
          "schema": {
            "type": "object"
          }
        }
      }
    }
  }
}

Gives:

interface Tasks {
  deleteTaskTemplate(req: DeleteTaskTemplateRequest): Promise<undefined>;
}

I've also allowed 201 responses and skip attempting to add interface properties if there's no schema defined for the respone (again to prevent client-cli throwing in this case). This is due to having a bunch of Java/Spring APIs in my organisation that return 201 respones with empty object bodies, example openapi schema I'm dealing with:

{
  "201": {
    "description": "Agent created successfully",
    "headers": {
      "Location": {
        "description": "Location URL of the newly created agent.",
        "style": "simple"
      }
    },
    "content": {
      "application/json": {}
    }
  }
}

Gives:

interface CreateAgentResponse {
}

[gunjam]

Forgot to add tests!

I tried adding a 204 endpoint to the movies fixture (like I did for the client change), but the openapi JSON that is generated has a 200 response:

{
  "/movies/{id}/{title}": {
    "put": {
      "operationId": "updateMovieTitle",
      "parameters": [
        {
          "schema": {
            "type": "string"
          },
          "in": "path",
          "name": "id",
          "required": true
        },
        {
          "schema": {
            "type": "string"
          },
          "in": "path",
          "name": "title",
          "required": true
        }
      ],
      "responses": {
        "200": {
          "description": "Default Response"
        }
      }
    }
  }
}

The plugin has the following code, what am I missing? 🤔

app.put('/movies/:id/:title', {
  schema: {
    operationId: 'updateMovieTitle',
    params: {
      type: 'object',
      properties: {
        id: { type: 'string' },
        title: { type: 'string' }
      },
      required: ['id', 'title']
    },
    responses: {
      204: {
        description: 'Successuly updated title'
      }
    }
  }
}, async (request, reply) => {
  await app.platformatic.entities.movie.save({
    fields: ['id', 'title'],
    input: {
      id: request.params.id,
      title: request.params.title
    }
  })
  reply.status(204)
})

[gunjam]

I found the answer 😄

[gunjam]

Dunno if I'm getting carried away but I decided to instead refactor in an attempt to support all 200 level response codes, including handling sceanrios where an API may have multiple types of success response.

In the case of multiple responses, I've appended the status to the interface name to avoid clashes.

As an example, an API I work with would produce the following types:

interface GetTaskResponseOK {...}
interface CreateTaskResponseCreated {...}
interface ClaimNextTaskResponseOK {...}

interface Tasks {
  getTask(req: GetTaskRequest): Promise<GetTaskResponseOK>; // 200
  createTask(req: CreateTaskRequest): Promise<CreateTaskResponseCreated>; // 201
  // This API returns 200 or 204 if there are no tasks left to claim
  claimNextTask(req: ClaimNextTaskRequest): Promise<ClaimNextTaskResponseOK | undefined>;  
}

Please let me know what you think.

Btw thanks for taking the time to review my changes over the last few weeks, I appreciate you're busy building platformatic and the features I need to integrate in my own organisation may not align with your own goals.
✨ ❤️ 🙏

[mcollina]

lgtm

[mcollina]

Good job! We are pretty busy with the conference season and all the features for the various launches.

Supporting folks adopting Platformatic is why we are here after all! Happy to have a private chat on how we can support you best.