Redocly / Redocly/redoc

Latest Redoc doesn't generate XML request bodies

Open
#492 17 comments 6 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

help wanted Type: Enhancement
Dominant language
TypeScript
Stars
25.9k
Forks
2.4k
Avg merge
13h 10m
Merged PRs (30d)
4

Description

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?

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by loading the provided spec_minimal.yaml with the Redoc standalone bundle and reproduce the requestBody rendering for application/json and application/xml. Trace how the VertexIn request body is converted into samples, then verify that the rendered documentation includes an XML sample alongside the JSON sample.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
api, documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
62/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.