Difference between Error Codes and HTTP Codes in the Response Error Details section?

SmartDocs method pages have a table at the bottom called Response Error Details with columns for HTTP Codes, Error Codes, and Descriptions. Whenever I create a method by importing a spec file, the Error Codes are identical to the HTTP Codes. Is there supposed to be a difference between them?

If the codes are supposed to be different, how can I specify Error Codes in my YAML file? Whatever I list under "responses" in my YAML shows up as the HTTP Code and Error Code. For example, the following code in a YAML renders as the image below.

      responses:
        '200':
          description: OK
        '400':
          description: Bad Request response
        '401':
          description: Unauthorized response
        '500':
          description: Server Error response

5495-screen-shot-2017-08-17-at-104041-am.png

I know I can manually edit Error Codes through the dev portal UI, but I would prefer all documentation be specified in the YAML. Any feedback is appreciated!

1 6 2,726
6 REPLIES 6

@Bennett Hansen , Great Question & Thank you for highlighting,

At present, I don't think there is any way to specify error codes apart from manually editing them in the UI. Ideally, Smartdocs should support openapi custom extensions which can be used in the smartdocs template. It's a powerful feature addition to smartdocs.

@marshg@google.com , @Chris Novak What do you think about OpenAPI custom extensions support to smartdocs ? It will be a very powerful & very much needed feature. Is there any way to achieve same today ? If not, What do you think about supporting same in smartdocs ?

No plans to add extensions to v1. We may consider for v2.

@Anil Sagar It looks like the errors section also includes all the response codes. For example if you have multiple success response codes they show up there. Except there is no way to tell what the first success response code is. Is there a way to access all the response codes in Smartdocs, I know the all but the first success response code are available in Apigee.APIModel.response.errors

I'm guessing that the "Response error details" was added to your template manually? SmartDocs v1 didn't consider response codes in favor of enabling developers to make live requests directly (whether that is well- or mal-formed) under the theory that learning happens best when doing.

That being said, this is an area we're considering for the future.

Thanks for the reply. I don't think the "Response Error Details" table was added manually - it's in the drupal-cms.hbr template on Apigee's GitHub repo (line 376 in https://github.com/apigee/smartdocs-templates/blob/master/templates/method/drupal-cms.hbr).

I suppose it would be easy enough to remove the redundant "Error Code" column from the table if there's no way to define that value in the YAML.