Swagger 生成的 API 没有返回值

Posted 2023-02-19

【中文标题】Swagger 生成的 API 没有返回值

【英文标题】：Swagger generated API does not have return value

【发布时间】：2019-05-19 11:00:42

【问题描述】：

我正在使用 swagger-codegen-3.0.0。

如下图，API规范有响应200和400；但是，在生成 addTeam() API 时，它会生成返回类型为 'void'。

我想处理响应代码 200 和/或 400。这是否意味着我已经在响应规范中明确定义了有效负载类型？有人可以提供有关我的“响应”规范应该如何的更多详细信息吗？

 49   /team:
 50     post:                                                                                           
 51       summary: Add team                                                                           
 52       operationId: addTeam                                                                        
 53       requestBody:                                                                                  
 54         description: Team detail being added                                                      
 55         content:                                                                                    
 56           application/json:                                                                         
 57             schema:                                                                                 
 58               type: array                                                                           
 59               items:                                                                                
 60                 $ref: "#/components/schemas/addTeamPayload"                                                                           
 61       responses:                                                                                    
 62         200:                                                                                        
 63           description: Ok                                                                           
 64         400:                                                                                        
 65           description: Bad request                                                                  
 66       tags:                                                                                         
 67         - Team

java -jar swagger-codegen-cli-3.0.0.jar generate -i teamApiSpec.yaml -l java --additional-properties jackson=true --artifact-id swagger-java-client-api

此命令生成以下 Java 代码/API。

/**
 * Add team
 * 
 * @param body Team detail being added (optional)
 * @throws ApiException If fail to call the API, e.g. server error or cannot deserialize the response body

 */
public void addTeam(List<AddTeamPayload> body) throws ApiException 
    addTeamWithHttpInfo(body);


/**
 * Add Team
 * 
 * @param body Team detail being added (optional)
 * @return ApiResponse&lt;Void&gt;
 * @throws ApiException If fail to call the API, e.g. server error or cannot deserialize the response body

 */
public ApiResponse<Void> addTeamWithHttpInfo(List<AddTeamPayload> body) throws ApiException 
    com.squareup.okhttp.Call call = addTeamValidateBeforeCall(body, null, null);
    return apiClient.execute(call);

另一个问题是即使在 API 规范中编写了 400 响应代码，当服务器返回 400 时，API 仍然会抛出异常，并且在处理过程中，返回代码详细信息会丢失。作为 API 的用户，我不知道返回什么返回码或服务器发送什么返回响应消息。

有人可以对此发表评论吗？这个很重要。如果我遗漏了 API 规范中的某些内容，请告诉我。

【参考方案1】：

如果您的服务返回数据，您应该在响应中添加内容描述。

  /team:
     post:                                                                                           
       summary: Add team                                                                           
       requestBody:                                                                                  
         description: Team detail being added                                                      
         content:                                                                                    
           application/json:                                                                         
             schema:                                                                                 
               type: array                                                                           
               items:
                 $ref: '#/components/schemas/addTeamPayLoad'
       responses:                                                                                    
         200:                                                                                        
           description: Ok
           content:
             '*/*':
              schema:
                type: object
         400:                                                                                        
           description: Bad request
           content:
             '*/*':
              schema:
                type: object
       tags:                                                                                         
         - Team

【讨论】：

但是当我这样做时会发生什么，因为我已经尝试过并且没有看到改进。返回 400 时会发生什么？

您是否为每种响应类型添加了内容部分？

我认为这个问题更多地与 Swagger Codegen 相关，对于非 2xx 响应，您会得到一个包含字符串的异常，而不是与架构类型对应的对象。我已经解决了它并继续前进。