Question

我一直在尝试根据official docs向我的Swagger API添加示例（请参见请求和响应正文示例的最后一个代码块），但它似乎无法按预期工作

考虑以下最小示例：

  @Override
    public void update(Village village) {
        String q = " UPDATE village "
                + "  SET  name = :name "
//                + "      ,panchayat_id = :panchayat_id "
                + "      ,name_hindi = :name_hindi "
                + "      ,status = :status "
                + "      ,update_date = :update_date "
                + "      ,update_by = :update_by "
                + "      ,update_by_name = :update_by_name "
                + "      ,dc_id = :dc_id "
                + "      ,loksabha_id = :loksabha_id "
                + "      ,census_code = :census_code "
                + "      ,pincode = :pincode "
                + "      ,area_type = :area_type "
                + "  WHERE village_id = :village_id ";
        MapSqlParameterSource param = new MapSqlParameterSource();
        param.addValue("village_id", village.getVillageId());
        param.addValue("panchayat_id", village.getPanchayat() != null ? village.getPanchayat().getPanchayatId() : null);
        param.addValue("name", village.getName());
        param.addValue("name_hindi", village.getNameHindi());
        param.addValue("status", village.getStatus());
        param.addValue("update_date", village.getUpdateDate());
        param.addValue("update_by", village.getUserdetail() != null ? village.getUserdetail().getUserId() : null);
        param.addValue("update_by_name", village.getUserdetail().getName());
        param.addValue("dc_id", village.getDc() != null ? village.getDc().getDcId() : null);
        param.addValue("loksabha_id", village.getLoksabha() != null ? village.getLoksabha().getLoksabhaId() : null);
        param.addValue("census_code", village.getCensusCode());
        param.addValue("pincode", village.getPincode());
        param.addValue("area_type", village.getAreaType());
        getNamedParameterJdbcTemplate().update(q, param);
    }

我想提供样本响应，一个具有可选属性swagger: "2.0" info: description: Desc version: "1" title: Title paths: /stuff: post: produces: - application/json responses: 201: description: It worked content: application/json: schema: $ref: "#/definitions/StatusMessage" examples: Success without message: value: code: "00000" Success with message: value: code: "00000" message: "All right" definitions: StatusMessage: type: object description: Response with code and optional message properties: code: type: string message: type: string required: - code，而另一个不带。但是，上述YAML文件在生成的API类中产生了错误的结果：

message

@ApiOperation(value = "", nickname = "stuffPost", notes = "", tags={ }) @ApiResponses(value = { @ApiResponse(code = 201, message = "It worked") }) @RequestMapping(value = "/stuff", method = RequestMethod.POST) default ResponseEntity<Void> stuffPost() { /*default implementation*/ }属性不存在，返回类型错误！此外，它不会在Swagger Editor：produces属性responses中进行编译。

我将其更改为在Swagger编辑器中获得“有效”示例，但生成的代码也是错误的。见下文：

should NOT have additional properties

生成的方法是：

paths:
  /stuff:
    post:
      produces:
      - application/json
      responses:
        201:
          description: It worked
          schema:
            $ref: "#/definitions/StatusMessage"
          examples:
            Success without message:
              code: "00000"
            Success with message:
              code: "00000"
              message: "All right"

这一次，@ApiOperation(value = "", nickname = "stuffPost", notes = "", response = StatusMessage.class, tags={ }) @ApiResponses(value = { @ApiResponse(code = 201, message = "It worked", response = StatusMessage.class) }) @RequestMapping(value = "/stuff", produces = { "application/json", "Success without message", "Success with message" }, method = RequestMethod.POST) default ResponseEntity<StatusMessage> stuffPost() { /*default implementation*/ }属性在那里，但是完全关闭了！

如何使它工作？如果我使用第二个版本并以produces作为示例标题的键，则该方法有效，但是由于键重复，我无法添加更多示例

Answer 1

来自Helen的comment：

该示例混合了OpenAPI 2.0（swagger: '2.0'）和OpenAPI 3.0（openapi: 3.0.0）语法。例如，content和examples是OpenAPI 3.0关键字，而definitions是2.0关键字。

examples（复数形式）在仅支持example的OpenAPI 2.0中不受支持-请查阅Adding Examples的2.0指南。

我在OpenAPI 2.0中针对此问题找到的解决方法如下：

paths:
  /stuff:
    post:
      produces:
      - application/json
      responses:
        201:
          description: It worked
          schema:
            $ref: "#/definitions/StatusMessage"
          examples:
            - code: "00000"
              message: "All right"
            - code: "00000"

这显示了两个示例（以0和1为标题），并且没有破坏Codegen。

如何在不破坏Codegen的情况下在Swagger中添加一些示例以进行响应？

1 个答案: