Skip to content

[REQ] "throws Exception" for specified APIs #4815

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
purple-dragon opened this issue Dec 17, 2019 · 0 comments
Open

[REQ] "throws Exception" for specified APIs #4815

purple-dragon opened this issue Dec 17, 2019 · 0 comments

Comments

@purple-dragon
Copy link

purple-dragon commented Dec 17, 2019

Is your feature request related to a problem? Please describe.

we have api.yaml definition

openapi: "3.0.2"
info:
  version: "1.0.0"
  title: "File Management API"
  description: >-
    File Management

paths:
  /api/v1/documents:
    post:
      tags:
        - Manage Files
      summary: "Upload new file"
      operationId: "createDocument"
      requestBody:
        content:
          multipart/form-data:
            schema:
              properties:
                file:
                  type: array
                  items:
                    type: string
                    format: binary
                metadata:
                  type: object
      responses:
        201:
          description: "Document created, return generated document information"
        404:
          description: "Not Found"
        409:
          description: "Conflict"
        500:
          description: "Internal Server Error"
    get:
      operationId: "getDocument"
      responses:
        200:
          description: "return document information"
        404:
          description: "Not Found"
        409:
          description: "Conflict"
        500:
          description: "Internal Server Error"

it generate APIs as below, no "throws Exception" generated, but we really need "throws" in some cases:

default ResponseEntity<Document> createDocument(@ApiParam(value = "file detail") @Valid @RequestPart("file") MultipartFile file,@ApiParam(value = "") @RequestParam(value="metadata", required=false)  Object metadata)

default ResponseEntity<Void> getDocument()

I found two related PR/issue

  1. remove "throws Exception"
    [JAX-RS][Spec] Removes throws Exception. swagger-api/swagger-codegen#7437
  2. add "throws Exception" with unhandledException flag, it's global flag for all APIs
    Add throws Exception directive to Spring operation methods #2482

directly remove/add "throws Exception" for all APIs are not good idea, since a part of APIs need it.

Describe the solution you'd like

I think we can use Open API "Specification Extensions", with additional flag "x-" to tell generator which API need throws, which don't need.
image

options:

Option 1. add x-operationId-exception: true/false  ---- boolean value

api.yaml:
paths:
  /api/v1/documents:
    post:
      operationId: "createDocument"
      x-operationId-exception: true

option1.1 generate logical:

if (x-operationId-exception == true/undefined && unhandledException == true) {
   generate "throws Exception"
} else if (x-operationId-exception == false && unhandledException == true) {
   // e.g. we have 10 APIs, only a few APIs(e.g. 1,2) doesn't need throws
   no throws generated
} else if (x-operationId-exception == true && unhandledException == false/undefined) {
  // e.g. we have 10 APIs, only a few APIs(e.g. 1,2) do need throws
  generate "throws Exception"
} else if (x-operationId-exception == false/undefined && unhandledException == false/undefined) {
  no throws generated
}

option 1.2
for simple, 
if(x-operationId-exception == true)  {
  generate "throws Exception"
} else {
  no throws generated
}
Option 2. add x-operationId-exception:  ---- string array

api.yaml:
paths:
  /api/v1/documents:
    post:
      operationId: "createDocument"
      x-operationId-exception: [MyException1, MyException2]

option 2.1 generate logical:

if (x-operationId-exception is defined) {
   // no need to check unhandledException
   generate "throws MyException1, MyException2"
} else if (x-operationId-exception is undefined) {
   if (unhandledException == true) {
       generate "throws Exception"
   } else {
      no throws generated
   }
} 

option 2.2
for simple, 
if(x-operationId-exception is defined)  {
  generate "throws MyException1, MyException2"
} else {
  no throws generated
}

Option 2 (for simple, option 2.2) may be better, how do you think?

Describe alternatives you've considered

Additional context

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

1 participant