Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

There's no visual indication whether a requestBody is required or not #2228

Open
isomorpheme opened this issue Aug 30, 2022 · 0 comments
Open

There's no visual indication whether a requestBody is required or not #2228

isomorpheme opened this issue Aug 30, 2022 · 0 comments
Labels
enhancement New feature or request hacktoberfest portal triaged

Comments

@isomorpheme
Copy link

Request Body objects have a required property (defaulting to false) that indicates whether a request body is allowed to be empty. As far as I can tell, the value of required isn't represented anywhere in the generated documentation for an operation.

Context

This makes the documentation for my API less clear, because downstream consumers e.g. assume they can safely omit a request body when that will actually cause errors.

Current Behavior

If an operation doesn't have required on its requestBody set, or has required: false, the "Body" section looks like this:

image

Setting required: true in the requestBody yields the exact same result.

Expected Behavior

There should be some indication that the request body is required, e.g. an orange "required" marker next to the "Body" heading, similar to how required fields on object schemas are marked.

Possible Workaround/Solution

The required status of a request body can be manually documented in e.g. the description of the request body, but that's error prone, and also plain annoying given the information is already there in the input YAML itself.

Steps to Reproduce

  1. Create index.html with the following contents:

    <!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
    <title>Elements in HTML</title>

    <script src="https://unpkg.com/@stoplight/elements/web-components.min.js"></script>
    <link rel="stylesheet" href="https://unpkg.com/@stoplight/elements/styles.min.css">
  </head>
  <body>

    <elements-api
      apiDescriptionUrl="api.yaml"
      router="hash"
    />

  </body>
</html>

  2. Create api.yaml in the same directory with the following contents:

    openapi: 3.0.3
info:
  title: Test API
  description: Test API
  version: 1.0.0
paths:
  /test:
    post:
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                foo:
                  type: string

  3. Serve the directory, e.g. using python3 -m http.server and view the page for POST /test.

  4. Add required: true to the requestBody.

  5. Refresh the page.

Environment

  • Version used: Whatever is latest on unpkg.com CDN
  • Environment name and version (e.g. Chrome 39, node.js 5.4): Firefox 103.0.2 (64-bit)
  • Operating System and version (desktop or mobile): Ubuntu 22.04
  • Link to your environment/workspace/project: N/A
@mnaumanali94 mnaumanali94 added the enhancement New feature or request label Sep 8, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
enhancement New feature or request hacktoberfest portal triaged
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
3 participants
@isomorpheme @mnaumanali94 @chohmann