Forum Discussion

pmong's avatar
pmong
New Contributor
8 years ago

Sharable error codes across APIs

I'm trying to create a page for error codes with examples which can be used across various APIs.

All these error codes have the same structure, which has attributes statusCode and statusMsg.

 

I have started using a domain, however example doesn't work. (I am using Swagger 2, as our gateway doesn't support OpenAPI 3)

I noticed the example keyword doesn't work, so I try x-example... while syntax is OK, that information isn't display on the UI.

 

 

info:
  version: '1'
  title: Error Code Domain
  description: Describe API error codes

definitions:
  ErrorModel:
    properties:
      statusCode:
        type: string
      statusMsg:
        type: string

responses:
  CONF001:
    description: Configuration error
    schema:
      $ref: '#/definitions/ErrorModel'
    x-example: 
      statusCode: CONF.001
      statusMsg: Configuration error

  DATA001:
    description: Invalid data
    schema:
      $ref: '#/definitions/ErrorModel'
    x-example: 
      statusCode: DATA.001
      statusMsg: Invalid data in input

 

 

In the API, under responses:

 

 

        400:
          description: Invalid data
          schema:
            $ref: 'https://api.swaggerhub.com/domains/xxx/ErrorCodesDomain/1#/responses/DATA001'

 

 

My questions is: What is the recommended way of sharing error codes? Particularly ones that has the same structure?

 

Thanks.

2 Replies

  • HKosova's avatar
    HKosova
    Icon for Alumni rankAlumni
    8 years ago

    Hi pmong,

     

    In OpenAPI 2.0, response examples can be specified using the examples.<media-type> keyword. Check out the Adding Examples guide for more information.

    responses:
  CONF001:
    description: Configuration error
    schema:
      $ref: '#/definitions/ErrorModel'
    examples:
      application/json:
        statusCode: CONF.001
        statusMsg: Configuration error

    Also, references to response definition (not schema definitions) should be like this:

            400:
          $ref: 'https://api.swaggerhub.com/domains/xxx/ErrorCodesDomain/1#/responses/DATA001' 

    After these changes your response example should work fine.

  • pmong's avatar
    pmong
    New Contributor
    8 years ago

    Thank you for correcting my response definition, that is working great.

     

    I just want to clarify the reason I want the example in the Domain is so they can also be shared across API.

    Is that possible? 

     

    Thanks.