swagger-api / swagger-api/swagger-ui

x-http-method-override header support not present creating issues

Open
#5,306 7 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

Swagger/OpenAPI definition:

'/toneprovide/catalogs':
   post:
     summary: browse a catalog/category (post method made get via override header)
     description: API interaction for browsing a category
     operationId: browseCatalogs
     tags:
       - catalog-management
     consumes:
       - application/json
     produces:
       - application/json
     parameters:
       - in: header
         name: X-HTTP-Method-Override
         type: string
         required: true
       - in: query
         name: startRecord
         description: start record of the category
         required: true
         type: string
         pattern: '\d{1,8}'
       - in: query
         name: total
         description: Total numbers of categories to be fetched
         required: true
         type: string
         pattern: '\d{1,5}'
       - in: body
         name: browseCatalog
         description: browse catalog information
         required: true
         schema:
           $ref: '#/definitions/BrowseCatalog'
     responses:
       '200':
         description: Success
         headers:
           x-huawei-rbt-total-count:
             type: string
             description: Total cont available for the requested resource.
         schema:
           type: object
           required:
             - status
             - count
             - type
             - results
           properties:
             status:
               type: string
             count:
               type: integer
               format: int64
             type:
               type: string
             results:
               type: array
               items:
                 $ref: '#/definitions/CatalogInfo'
       '400':
         description: Bad Request
         schema:
           $ref: '#/definitions/ErrorResponse'
       '401':
         description: Unauthorized
         schema:
           $ref: '#/definitions/ErrorResponse'
       '403':
         description: Forbidden
         schema:
           $ref: '#/definitions/ErrorResponse'
       '500':
         description: Internal Server Error
     externalDocs:
       url: 'http://api.example.com/docs/user-operations/categories'
       description: Learn more about Video operations provided by this API.
   post:
     summary: Add a catalog/category
     description: API interaction for operator adding a category
     operationId: addCatalog
     tags:
       - catalog-management
     consumes:
       - application/json
     produces:
       - application/json
     parameters:
       - in: body
         name: catalog
         description: catalogInformation
         required: true
         schema:
           $ref: '#/definitions/Catalog'
     responses:
       '200':
         description: Success
         schema:
           type: object
           required:
             - status
             - count
             - type
             - results
           properties:
             status:
               type: string
             count:
               type: integer
               format: int64
             type:
               type: string
             results:
               type: array
               items:
                 type: string
       '400':
         description: Bad Request
         schema:
           $ref: '#/definitions/ErrorResponse'
       '401':
         description: Unauthorized
         schema:
           $ref: '#/definitions/ErrorResponse'
       '403':
         description: Forbidden
         schema:
           $ref: '#/definitions/ErrorResponse'
       '500':
         description: Internal Server Error
     externalDocs:
       url: 'http://api.example.com/docs/user-operations/categories'
       description: Learn more about Video operations provided by this API.

### Is your feature request related to a problem?
Generally PUT, DELETE and PATCH methods are not supported at the production servers. To handle this we use POST with x-http-method-override in server code to handle PUT, POST and DELETE methods. Sometimes GET request as POST as well for request which required passing too many filter requests.
### Describe the solution you'd like
<!-- A clear and concise description of what you want to happen. -->
Swagger as of now does not allow multiple POST requests for a single Url even though header difference is there.
So the only option stays here to specify them as POST, PUT, DELETE and GET only.

The issue this creates is while generating client code using swagger-codegen-cli as it create sending request for the specified methods as per the document.
### Describe alternatives you've considered
<!--
 A clear and concise description of any alternative solutions or features
 you've considered.
-->
Request you to provide how the problem can be solved.
Can such feature support be expected in future. As such issues are making using swagger un-usable.

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 from the supplied Swagger/OpenAPI path definition and compare it with the request generated by swagger-codegen-cli. Determine how two POST operations at one URL, distinguished by X-HTTP-Method-Override, should be represented and whether the change belongs in Swagger UI or client generation. Done means the supported representation and expected generated request behavior are defined and tested.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, openapi
Domain
api, documentation
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.