Latest Redoc doesn't generate XML request bodies

tmarkovich commented 6 years ago

I'm attempting to use redoc to generate documentation for an API that takes both XML and JSON requests, but it appears that redoc isn't able to generate samples for the requestBodies of type application/xml.

Here is a minimal YAML file:

openapi: "3.0.0"
servers:
  - url: //0.0.0.0
    description: Dummy Server

info:
  version: 0.0.1

# Tags -- grouping of endpoints
tags:
  - name: vertex
    description: |
      Endpoints associated with vertex operations

# The Paths / Endpoints
paths:
  # Vertex endpoints
  /nuos/add_vertex:
    post:
      operationId: add_vertex
      tags:
        - vertex
      summary: Adds the vertex to the graph
      requestBody:
        $ref: '#/components/requestBodies/VertexIn'
      responses:
        200:
          description: Returns success if it was successful
      x-code-samples:
        - lang: shell
          source: "curl -X post 0.0.0.0:1024/nuos/add_vertex -d @nuos-add-vertex.json"
#definitions
components:
  schemas:
    # Vertex Schemas
    VertexIn:
      type: object
      required:
        - id
      properties:
        id:
          description: The GUID for the vertex
          type: string
          example: "0653e070-9e26-46a2-9833-acb0145e5587"
      xml:
        name: vertex
  requestBodies:
    # Vertex RequestBodies
    VertexIn:
      content:
        application/json:
          schema:
            allOf:
              - description: The vertex to read in
                title: Vertex
              - $ref: '#/components/schemas/VertexIn'
        application/xml:
          schema:
            allOf:
              - description: The vertex to read in
                title: Vertex
              - $ref: '#/components/schemas/VertexIn'
      description: The vertex to add to the graph
      required: true

and using

<!DOCTYPE html>
<html>
    <head>
    <title>Forge.AI Internal Knowledge Graph ReDoc</title>
    <!-- needed for adaptive design -->
    <meta charset="utf-8"/>
    <meta name="viewport" content="width=device-width, initial-scale=1">

    <!--
         ReDoc doesn't change outer page styles
       -->
    <style>
     body {
             margin: 0;
             padding: 0;
     }
    </style>
    </head>
    <body>
    <redoc spec-url='./spec_minimal.yaml'></redoc>
    <script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"> </script>
    </body>
</html>

I get the following output: screen shot 2018-05-15 at 1 50 16 pm

By contrast, when I use the same YAML file in the editor at https://editor.swagger.io, I get the output that I'd expect: screen shot 2018-05-15 at 1 50 41 pm

Is there a way to get redoc to generate the desired XML requestBody samples?

gerbil commented 6 years ago

Exactly! +1 Please advise how (and where) can we fix this issue, it's critical to the project so far..

tmarkovich commented 6 years ago

@gerbil I just included the example request in the description of the endpoint for the time being. It's not near as nice, but it serves the stopgap measure until it's either fixed or I get around to migrating off redoc.

gerbil commented 6 years ago

@tmarkovich can you post a full example here? i'm quite new to this kind of things..

RomanHotsiy commented 6 years ago

Hey @tmarkovich, @gerbil

this can be workaround-ed. You can put example into example section of your Media Type Object and it will be rendered near the JSON example:

components:
  # ...
  requestBodies:
    # Vertex RequestBodies
    VertexIn:
      content:
        application/json:
          schema:
            allOf:
              - description: The vertex to read in
                title: Vertex
              - $ref: '#/components/schemas/VertexIn'
        application/xml:
          # v=========v note example below
          example: |
            <?xml version="1.0" encoding="UTF-8">
              ...
            </xml>
          schema:
            allOf:
              - description: The vertex to read in
                title: Vertex
              - $ref: '#/components/schemas/VertexIn'
      description: The vertex to add to the graph
      required: true

Let me know if this is what satisfies your use case!

Automatic XML sample is not planned for the near feature. But you can try to implement it yourself. Maybe code from swagger-ui can be reused. Let me know if you need any guidance on how to start!

mdwyer223 commented 5 years ago

Hey so I was trying to do the same as above. Here is the file:

info:
  title: Hello world
  version: 0.1.0
  description: This is a default test for the xml parsing

paths:
  /tests:
    get:
      summary: Testing
      responses:
        '200':
          description: good to go
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/basicobject'

components:
  schemas:
    basicobject:
      type: object
      properties:
        id:
          type: integer
          example: 64
        name:
          type: string
          example: Ben Dover

And I am referencing the ReDoc tag like this: `

"; echo ""; } else { echo "

Please specify a proper file. The file specified is missing or there is no file specified.

"; } ?>

` However I am not able to get the application/xml drop down to appear within the GUI. ![image](https://user-images.githubusercontent.com/4520029/52066954-81142e80-2547-11e9-8976-7d3d020c25c7.png) Is there anything that I should be doing to debug or fix this issue?

SupremeTechnopriest commented 5 years ago

Custom response examples are being rendered as a hash map of characters instead of text:

   *     responses:
   *       200:
   *         description: Returns the median statistics for the supplied date range in the supplied buckets.
   *         content:
   *           application/json:
   *             schema:
   *               $ref: '#/definitions/StatsMedian'
   *           application/xml:
   *             example:
   *               $ref: '#/definitions/StatsMedianXML'
   *             schema:
   *               $ref: '#/definitions/StatsMedian'

 *   StatsMedianXML: |
 *     <?xml version="1.0" encoding="UTF-8"?>
 *       <data>
 *         <bucket>
 *           <item>2019-05-01T00:00:00.000Z</item>
 *           <item>2019-06-01T00:00:00.000Z</item>
 *         </bucket>
 *       </data>
 *     </xml>

SupremeTechnopriest commented 5 years ago

Is this because im using $ref?

SupremeTechnopriest commented 5 years ago

It appears so... Would be nice to be able to use a ref here.

KamalPatel365 commented 4 years ago

Hey @tmarkovich, @gerbil

this can be workaround-ed. You can put example into example section of your Media Type Object and it will be rendered near the JSON example:
components:
  # ...
  requestBodies:
    # Vertex RequestBodies
    VertexIn:
      content:
        application/json:
          schema:
            allOf:
              - description: The vertex to read in
                title: Vertex
              - $ref: '#/components/schemas/VertexIn'
        application/xml:
          # v=========v note example below
          example: |
            <?xml version="1.0" encoding="UTF-8">
              ...
            </xml>
          schema:
            allOf:
              - description: The vertex to read in
                title: Vertex
              - $ref: '#/components/schemas/VertexIn'
      description: The vertex to add to the graph
      required: true
Let me know if this is what satisfies your use case!

Automatic XML sample is not planned for the near feature. But you can try to implement it yourself. Maybe code from swagger-ui can be reused. Let me know if you need any guidance on how to start!

But it will unnecessary increase the size of our specification @RomanHotsiy

KamalPatel365 commented 4 years ago

@RomanHotsiy I just want to know how to add the XML content type support in ReDoc.

ElizabethM-fourth commented 1 year ago

I am having this same issue. My openapi/swagger file is generated by Swashbuckle (.Net) and I cannot see how I'd add an XML example in the code base; let alone the whole point being that swagger is supposed to solve documentation getting out of step from the code (and adding in manual examples sounds like a recipe for disaster here).

mayankbhatt07141 commented 1 year ago

Our project uses both XML and JSON, but I am unable to see the XML request body in the documentation. Has anyone had any luck with this?

rishitank commented 1 year ago

Any progress on this? Or has anyone been able to override the default behaviour to provide support for XML request / response body generation? As far as I can tell the code responsible lives here: https://github.com/Redocly/redoc/blob/7e4639e8cf558d84239762e867238d952f4ed422/src/services/models/MediaType.ts#L49

embario commented 1 year ago

+1 for this feature. Would love to see response rendering of our server's XML responses.

rishitank commented 1 year ago

This feature has been implemented (at least for response examples) in https://github.com/Redocly/redoc/pull/2347 and could be reused for requests.

dfcoffin commented 6 months ago

I am trying to document an API that uses a REST request interface and produces an application/atom+xml response. Is there a workaround to provide examples, since only application/json generates code examples? Allowing application/atom+xml as a content type with the workaround will help.

Redocly / redoc

Latest Redoc doesn't generate XML request bodies #492