User Feedback - Updating API Elements

RFCs (Request for Comments)
#1

We’re looking for feedback from users that are using the updating API element feature.

Please add to this thread for any issue you’ve encountered when validating your API elements against your schema or if you have any suggestion around the feature’s UX.

We’ll be summarising feedback as it comes in this first post. :slightly_smiling_face:

Feedback:

  • FIXED - Endpoints added to the schema are not added to the collection (ref)
  • FIXED - If you have “variables” into root “servers” field then all endpoints will return “Request not found in schema…” message when trying to validate. (ref)
  • FIXED - If you have “parameters” or “responses” into root “components” field and use $ref on it in your endpoints, you will get “Headers not found in schema:” and “Response headers not found in schema:” messages when trying to validate.(ref)
  • FIXED - Integer and boolean fields will be converted to “field”: “” (“field”: “”). Sometimes the proposed fixes are incorrect (“field”: null) when trying to validate. (ref)
  • FIXED - When defining an API schema that uses root as it’s path, the collection generated causes collection schema validation error. (ref)
3 Likes
#2

I posted in github PR but anyway replying here =)

Thanks guys, excellent feature.

Testing here, and for me, the new one’s methods/actions added in API doesn’t appear to include on updating the collection

1 Like
#3

@scaloni thanks for the feedback! We are working on it and new endpoints will soon appear as updates to be added to the collection.

2 Likes
#4

I tried to use this feature for my OpenApi 3.0 scheme but came across a lot of problems.

  1. If you have “variables” into root “servers” field then all endpoints will return “Request not found in schema…” message when trying to validate.
Servers scheme 
servers:
  - url: '{BASE_URI}/api'
    description: Development server
    variables:
      BASE_URI:
        default: http://example.com
        description: Server base URI
  1. If you have “parameters” or “responses” into root “components” field and use $ref on it in your endpoints, you will get “Headers not found in schema:” and “Response headers not found in schema:” messages when trying to validate.
  2. Integer and boolean fields will be converted to “field”: “<integer>” (“field”: “<boolean>”). Sometimes the proposed fixes are incorrect (“field”: null) when trying to validate.

I would really like to use this feature, but unfortunately it is not yet ready for use :disappointed:

#5

Hey, I found out that when a new endpoint is being added from the validation web page, its responses aren’t added.

#6

Hey @asafk, thanks for reporting here. We were unable to reproduce this issue. Would it be possible to share the schema and collection? It will help us in triaging the issue.

#7

Hey @sshultchov, thanks for reporting here. We have identified the issues. This will be fixed soon :slight_smile:

1 Like
#8

Hi, I retried to reproduce it with a single request and couldn’t. I’ll update when it’ll happen again

#9

Hey @sshultchov :slightly_smiling_face:

We’ve just pushed fixes that should solve the issues you were facing. Could you give it another try and let us know if it works as expected now?

#10

Lots of issues trying to generate docs from an OpenAPI 3 spec:

  1. Folders are created for nested paths but don’t use descriptions from the paths. No option to not create folders
  2. Authorization information doesn’t show the key name or location (eg. in header) from securitySchemes
  3. Examples aren’t used from the schema’s examples for path parameters (shows “/requests/:id” in the Example Request instead of using the example value for :id)
  4. Path parameters using $ref don’t show description
  5. Making changes to the API in Postman app and saving doesn’t update Documentation collection most of the time (and there’s no way to force an update). Last updated timestamp never seems to change after the initial generation. (So what I do know is delete the documentation collection and generate a new one with the same name… :sob: )
  6. A POST method that has form data in requestBody doesn’t show any information about the request body in the documentation at all. It also doesn’t show the query parameters in the documentation at all. The Example Request includes the query parameter and the form data (though it doesn’t serialize the nested object – with square brackets – as desired)

So… all in all, a good start but definitely not ready for documenting APIs via the API Builder yet.

#11

Hey, @davemyron thanks for the feedbacks. :smiley:

Here are some updates regarding the points that you have raised:

  1. For folder creation, you can use the option Folder organization while generating under Advanced Options dropdown, here if you choose Tags as value than request will fall under a folder named based on tags if present otherwise under no folder (directly under collection), also it will have a description from tag object. For Paths option as a folder can be generated from path segments too, which does not have any description so there would be no description. And for now yes there is no way to not generate folders.

  2. Authorization is included as part of collection request property, you can see it set under Authorization tab of request/folder/collection. Thus no header will be present but when you send request Authorization header will be sent with it.

  3. In path /requests/:id id is a path variable, it is represented as such in UI. You can find value of path variable under “Path Variables” table under “Params” tab in request.
    We are working on an issue where example from example of parameter is not picked. You can find issue details here.

  4. We were not able to reproduce the issue mentioned by you, can you provide sample input for us to look more into it.

  5. It seems like that you’re asking for auto syncing of schema to the relation. Which is in the making.

Hope this helps!

1 Like
#12

A couple things I’ve noticed as I’ve been trying out this feature:

  • Not all schema changes seem to be detected during validation. I changed the default value of a request parameter and then ran validation against a Documentation element. It didn’t detect any changes.
  • There doesn’t appear to be a way to link request and response examples in Documentation. If I have examples of both a valid request and an invalid request it would be nice to link them to the corresponding valid/invalid response examples.
#13

I’m having a really annoying problem with API Builder whereby it keeps screwing up the Content-Type headers.

My schema has:
parameters:
- schema:
type: string
default: text/csv
in: header
name: Content-Type
required: true

And the validator keeps saying that it needs to add a new Content-Type with the exact value and when I have it make the updates, it’s just duplicating the same header in the Collection. Then if you validate again, it’ll keep repeating this, i.e. adding more of the same header to the Collection.

On one of my methods it also did a similar behavior for the Authorization header.

#14

Hey @jesse thanks for the feedback.

  1. Can you please provide a sample schema with which you are facing the issue ? We’d want to take a deeper look at this.

  2. Can you please elaborate on what are you trying to achieve here ? For now we do support adding examples (response) to a request of a collection.

#15

Hey, @alanwill Thanks for the feedback.

Can you please provide us a sample schema with which you are facing this problem ? We’re unable to reproduce the issue on our end.