swagger-api / swagger-api/swagger-ui

Can we add a component or a section to add buissness or technical error for the API ?

Open
#9,882 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
JavaScript
Stars
29k
Forks
9.3k
Avg merge
2d 23h
Merged PRs (30d)
25

Description

Content & configuration

I use the swagger-ui to document my APIs , I have to add the business error codes that those APIs return in response ,I see that is not part of the openApi specification so I did an alternative solution based on the tag "description" in the yaml file.

OpenAPI definition:

                application/xml:
                 schema:
                   $ref: '#/components/schemas/GetProductDetailsV35Rq'
           responses:  
             200:
               description:
                       <div>
                               Successful
                               <p>Business Error Codes &#58;</p>
                               <table>
                                     <tr>
                                       <th>Error code</th>
                                       <th>Error Description</th>
                                     </tr>
                                     <tr>
                                       <td>31101</td>	
                                       <td>Invalid Catalog Product Id</td>
                                     </tr>
                                     <tr>
                                       <td>31102</td>	
                                       <td>Invalid Catalog Product version</td>
                                     </tr>
                                      <tr>
                                        <td>31103</td>	
                                        <td>Catalog Product Pack Code</td>
                                     </tr>
                               </table>
                       </div> 

### Describe the solution you'd like
I added the table of error codes using the "description" tag in the yaml ,this is rendered as : 
![test](https://github.com/swagger-api/swagger-ui/assets/16072199/0bd7c09c-bdf0-4461-bd0f-8b169ade6b8d)

### Describe alternatives you've considered
 I'm asking if we can add a component that we can use it to display the error codes without use the yaml "description" tag

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing how Swagger UI renders OpenAPI response descriptions, especially the HTML table currently embedded in the response description. Determine whether the requested business and technical error-code component belongs in the OpenAPI definition or in Swagger UI, then define the supported input and rendered result before implementation.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, openapi
Domain
documentation, frontend
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.