Latest Redoc doesn't generate XML request bodies

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:

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:

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

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

@gerbil

@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.

@tmarkovich

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

@tmarkovich

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!

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:
`

<?php
    if($redoc_load) {
        echo "<redoc spec-url='$path_to_yaml'></redoc>";
        echo "<script src='https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js'> </script>";
    }
    else {
        echo "<p>Please specify a proper file. The file specified is missing or there is no file specified.</p>";
    }
?>

</div>

`

However I am not able to get the application/xml drop down to appear within the GUI.

Is there anything that I should be doing to debug or fix this issue?

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>

Is this because im using $ref?

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

@tmarkovich

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

@RomanHotsiy

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

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).

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?

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:

redoc/src/services/models/MediaType.ts

Line 49 in 7e4639e

this.generateExample(parser, info);

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

This feature has been implemented (at least for response examples) in #2347 and could be reused for requests.

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.

i had to turn off this linting rule on redocly.yaml to allow the XML examples to be present when the YAML schema says type: object

no-invalid-media-type-examples: off

can Redoc take XML seriously please...

Thank you for your interest in this issue.
We released Redoc v3, and it automatically generates request and response samples for XML media types such as application/xml.

Closing this as fixed in v3.0.0.

If an XML media type still shows no sample with v3, please open a new issue with the definition.

Navigation Menu

Repository navigation

Latest Redoc doesn't generate XML request bodies #492

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Latest Redoc doesn't generate XML request bodies #492

Description

Activity

gerbil commented on May 22, 2018

tmarkovich commented on May 22, 2018

gerbil commented on May 22, 2018

RomanHotsiy commented on May 22, 2018

mdwyer223 commented on Jan 31, 2019

SupremeTechnopriest commented on Jun 14, 2019

SupremeTechnopriest commented on Jun 14, 2019

SupremeTechnopriest commented on Jun 14, 2019

KamalPatel365 commented on Apr 1, 2020

KamalPatel365 commented on Apr 1, 2020

ElizabethM-fourth commented on Apr 17, 2023

mayankbhatt07141 commented on May 27, 2023

rishitank commented on May 31, 2023

embario commented on Jun 8, 2023

rishitank commented on Jun 29, 2023

dfcoffin commented on Apr 26, 2024

mykelscappin commented on Mar 23, 2026

AlexVarchuk commented on Oct 15, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions