Some getting started questions: multiple 200s, required parameters and explicit date formats

Hi there - just getting started with Stoplight and trying to port over some existing documentation. Here are 3 quick points that I’m currently a little stuck on:

  • It seems in the response definitions, you can only have one example for each response code (new examples overwrite the existing one). For some endpoints we want to document a couple of potential responses that would all have a 200 code, depending on the parameters supplied. Is that possible?
  • I’m trying to use referenced parameters to avoid duplication, but when I link parameters, the required toggle becomes greyed out. How can I mark these parameters as required?
  • I’m marking some fields as dates, but can I also explicitly give the date format? I’ve generally only been using regex in the pattern field, but is it OK to also use that to show something like yyyy-mm-dd?

Thanks in advance!

Oh - and point 4 …

For our latest supported endpoint versions, we have paths like:

example.com/api/2.1/model/action1
example.com/api/2.0/model/action2

I can see how to create versions and releases in a project. These seem to start by duplicating all the existing endpoint definitions.

As an end product, I’d want a single documentation hub, using whatever the latest endpoint version is for each path. What is the recommended way to manage that?

This is a limitation of OpenAPI 2. In OpenAPI 3, you can have multiple example responses of the same type. If you want to try out our new editor with visual OpenAPI 3 support, I can send you a link to the beta that is going on right now.

I see what you mean. I’m not sure why it is doing that. I’m checking with the team about it.

This should be okay. Patterns can be anything you can write a regex for. It just might not show up as nicely in the read view like date would.

Not using the versions feature seems like a good option for you if you want your API documentation to have different versioned endpoints right next to each other.

With the versions feature, a dropdown is created within your Hub that allows the end user to select the version they want to see, but the different versions won’t be on the same page at once.

I hope this helps!

Coming back to this, you technically can mark it required where you create the parameter itself, but it isn’t in the UI. If you go to the Code view, you can change false to true. The reason why you can’t do it in the operation itself is because according to the spec, properties outside of the reference are ignored. This does make it not possible to do on an operation by operation basis though.

Great - thanks for the quick responses!

Setting the required field in the code for the parameter worked great. For most cases I imagine things I set up as parameters will always be required across operations.

Good to know about the OAS2 vs 3 differences with the response options. I’ll let you know if we want to give the beta a go but will see how far I can get with the current version first.

1 Like

For this it seems sensible to maintain the docs under “major version” releases (i.e. just 1.0, 2.0, 3.0). Is it possible to delete an unwanted version number? I can see the trashcan to unpublish a release, but do I need to get under the hood to remove a version?

Sadly, we’ll need to delete an old version for you on our end.

Just send an email to support@stoplight.io with the project and version number and they can get it done for you.