redoc: 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: 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?

About this issue

Original URL
State: open
Created 6 years ago
Reactions: 5
Comments: 16 (1 by maintainers)

Most upvoted comments

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

rishitank on Jun 29, 2023

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

embario on Jun 8, 2023

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!

RomanHotsiy on May 22, 2018