Latest Redoc doesn't generate XML request bodies #492

tmarkovich · 2018-05-15T17:54:43Z

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?

The text was updated successfully, but these errors were encountered:

gerbil · 2018-05-22T04:01:21Z

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

tmarkovich · 2018-05-22T04:41:15Z

@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 · 2018-05-22T04:47:38Z

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

RomanHotsiy · 2018-05-22T09:12:08Z

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 · 2019-01-31T16:02:17Z

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?

SupremeTechnopriest · 2019-06-14T23:50:10Z

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 · 2019-06-14T23:51:23Z

Is this because im using $ref?

SupremeTechnopriest · 2019-06-14T23:53:50Z

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

KamalPatel365 · 2020-04-01T09:43:46Z

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 · 2020-04-01T09:45:41Z

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

ElizabethM-fourth · 2023-04-17T09:06:09Z

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 · 2023-05-27T17:47:45Z

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 · 2023-05-31T18:35:42Z

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

embario · 2023-06-08T15:16:14Z

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

rishitank · 2023-06-29T08:50:36Z

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

dfcoffin · 2024-04-26T18:58:10Z

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.

RomanHotsiy added help wanted feature labels May 22, 2018

RomanHotsiy mentioned this issue Jun 1, 2018

Any plans for support xml samples for request/response ? #171

Closed

RomanHotsiy mentioned this issue Apr 27, 2020

List of Open API 3.0 features that are not supported by [email protected] ( Release 2.0.0-alpha.32 ) #592

Closed

tayfun mentioned this issue Nov 17, 2021

Model API QA: Errors met when testing model training and replacing loaded model RasaHQ/rasa#10148

Closed

lornajane added Type: Enhancement and removed feature labels Jul 28, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Latest Redoc doesn't generate XML request bodies #492

Latest Redoc doesn't generate XML request bodies #492

tmarkovich commented May 15, 2018

gerbil commented May 22, 2018

tmarkovich commented May 22, 2018

gerbil commented May 22, 2018

RomanHotsiy commented May 22, 2018

mdwyer223 commented Jan 31, 2019 •

edited

Loading

SupremeTechnopriest commented Jun 14, 2019 •

edited

Loading

SupremeTechnopriest commented Jun 14, 2019

SupremeTechnopriest commented Jun 14, 2019

KamalPatel365 commented Apr 1, 2020

KamalPatel365 commented Apr 1, 2020

ElizabethM-fourth commented Apr 17, 2023

mayankbhatt07141 commented May 27, 2023

rishitank commented May 31, 2023

embario commented Jun 8, 2023

rishitank commented Jun 29, 2023 •

edited

Loading

dfcoffin commented Apr 26, 2024

Latest Redoc doesn't generate XML request bodies #492

Latest Redoc doesn't generate XML request bodies #492

Comments

tmarkovich commented May 15, 2018

gerbil commented May 22, 2018

tmarkovich commented May 22, 2018

gerbil commented May 22, 2018

RomanHotsiy commented May 22, 2018

mdwyer223 commented Jan 31, 2019 • edited Loading

SupremeTechnopriest commented Jun 14, 2019 • edited Loading

SupremeTechnopriest commented Jun 14, 2019

SupremeTechnopriest commented Jun 14, 2019

KamalPatel365 commented Apr 1, 2020

KamalPatel365 commented Apr 1, 2020

ElizabethM-fourth commented Apr 17, 2023

mayankbhatt07141 commented May 27, 2023

rishitank commented May 31, 2023

embario commented Jun 8, 2023

rishitank commented Jun 29, 2023 • edited Loading

dfcoffin commented Apr 26, 2024

mdwyer223 commented Jan 31, 2019 •

edited

Loading

SupremeTechnopriest commented Jun 14, 2019 •

edited

Loading

rishitank commented Jun 29, 2023 •

edited

Loading