redoc
redoc copied to clipboard
Redocly
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 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 can you post a full example here? i'm quite new to this kind of things..
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>
Hey @tmarkovich, @gerbil
this can be workaround-ed. You can put example into
examplesection 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: trueLet 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 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: https://github.com/Redocly/redoc/blob/7e4639e8cf558d84239762e867238d952f4ed422/src/services/models/MediaType.ts#L49
+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 https://github.com/Redocly/redoc/pull/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.
