Documenting error codes definition in Swagger API contract

Question

Imagine you are working under following circumstances:

You have REST API modules with API documentation generated into swagger-ui.html
Possible HTTP status codes for endpoints are documented well via io.swagger.annotations.* on controller method level for each endpoint.

In case of some error state (4XX or 5XX) application replies with ErrorResponseDTO with structure like

"ErrorResponseDTO": {
  "type": "object",
  "properties": {
     "errorCode": {
       "type": "integer",
       "format": "int32"
     },
    "message": {
      "type": "string"
    }
  }
}

Application have tens of errorCodes (within range like 1 - XX and please consider them as a legacy definiton without an easy way to change them).
List of errorCodes is relevant for the whole application so you prefer to keep their definiton list/table in overall API documentation rather then maintaining errorCodes definiton for each API endpoint separately.

Now you are looking for an effective way how to document these application error codes into API contract.

The approach of including a list of errorCodes with codes description into generated swagger-ui.html seems like a better way to keep API documentation up to date instead of having static and handwritten codes definition table attached in Markdown format in some Readme file.

Would you please have any recommendation how to document various codes which your applications produce?

Do you follow some specific good practice in this topic?

Thank you in advance.

score 0 · Answer 1 · answered Nov 16 '21 at 22:18

Meanwhile within a small internal dev team and with frequent API extensions there can be used generated swagger-ui with included error codes:

  @Bean
  public Docket swaggerSettings() {
    ApiSelectorBuilder builder = new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(
        new ApiInfoBuilder()
          .title("Response errorCodes table")
          .description(RestResponse.generateErrorsDocumentation().toString())
          .build()
      )
      ...
      .select();

    return builder.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
        .paths(PathSelectors.any())
        .build()
        .useDefaultResponseMessages(false);
  }

Documenting error codes definition in Swagger API contract

1 Answers1