Information request


(Reda) #1

Hi,
I’ve sent several messages by mail & chat, but never heard back from you, so i’m wondering if there is anyone behind this great tool that i’m enjoying but lacking in some fields…

Thanks


(Taylor Barnett) #2

Hey @reda,

I’m sorry about that. I see a message you sent on Friday. Were there other messages? We usually answer all support messages within a day during work hours, but Fridays sometimes get carried into Mondays. I know that isn’t always great, but the support team works hard on addressing issues with time and urgency in mind.

Could you explain your question a bit more? I didn’t see one in the original message. The more detailed the initial question, the more likely we can get you a quicker resolution to your question.


(Reda) #3

Thank you Taylor for your reply, you really made me happy :slight_smile:

Bellow is the last message sent:

We are currently trying your amazing tool stoplight, and we are enjoying the experience. Thank you for your good work.

I have watched several tutorials and read your doc, it kinda fit my need except some little details where I’m stuck and hope you can help me see clearer.

1- I’m very confused in how I should deal with the User (id, first_name, last_name, email, password, phone, created_at, …)
Let’s say I need to create 3 endpoints:

  • Newsletter opt-in in which I need only the email address
  • Contact in which I need only first_name, last_name & email,
  • Signin where I’ll need only the email & password

Is it possible to create 1 single model named User, from which I can refer only some properties?
For example regarding the endpoint Signin, I’ll point that I need Email and Password from the model User

Also for example regarding the Signup, I’ll mention that in the request body, I’ll need first_name, last_name, email, phone from the model User

2- Is it possible to structure endpoints and models in nested folders?

3- When creating an endpoint and inheriting from a model ($ref), Is it possible to inherit also the model example?

4- I would like to report a little bug that I noticed, when editing endpoint then click on save, it unfortunately doesn’t save, and display the initial value. I have to do the editing directly in JSON Schema. (I m using the standalone app Version 0.15.3 (0.15.3) on Mac OS)

Hope I was clear and you perfectly understood my need

Thank you


(Taylor Barnett) #4

First, I want to make sure we are looking at the same version and documentation at next.stoplight.io and docs.stoplight.io. It sounds like you might be using the old version and its desktop app. You can download the latest desktop app here: https://github.com/stoplightio/desktop/releases/tag/v4.8.1

It is a separate account from our older version, so you might need to make a new account if you don’t already have a Stoplight Next account. You should though from logging into the forum.

  1. It sounds like object inheritance would be beneficial for this use case. You could have a base User model with the information that all of the endpoints share (email) and create models that inherent from that model. You can mark certain properties as required in these models. You won’t be able to create one model that works for everything, since not all these endpoints will have the same required properties to work. We wrote some more docs on it here:
  1. You can structure things in a more folder like structure in your documentation Hub. But how you model your specification document is limited to how the OpenAPI specification is structured.

  2. Right now in Stoplight Next’s UI, you can’t declare an example for a model unless it is in an endpoint. So there would be nothing to inherit.


(Reda) #5

Thank you dear taylor for your reply.

First of all, yes, i was using the old version of stoplight ! I have downloaded the new one (stoplight next 4.8.1).

When exporting from Stoplight and importing in Stoplight Next, I see under “MODELING” the name of the project.oas2, does that mean I’m under OpenAPI 2? if yes, is there a way to export using OpenAPI v3?

aside from that, it says i have some errors and warnings, so I’m wondering what’s the best way to transfer my data from the old app to the new one

Thanks

EDIT: Hi Taylor dont bother to answer this post, we decided to rewrite everything from scratch usingg OpenAPI v3


(Reda) #6

Hi again, I played around the new version and it’s much better than the old one, and it already has most of the improvements i was going to send you in my next email :slight_smile: why did you call it “next” by the way?? :slight_smile:

regarding your reply:

this is exactly what I’m doing, bu I guess you didn’t really understand me well. But i’ll ask it again differently. Following the example you gave me about Object Inheritance, the base type model is “Car”, then you extended it with 2 new properties off-road & ground-clearance. Let’s say i’ll need off-road in 2 or 3 other different models, what would be the best practice for that?

another example would be still about a user, the base type model is “User”, that has fname, lname, email, phone. what would you do to create a “Signin” endpoint that contains email& password?? the solution i opted for now is to duplicate the email property, is that right?

You can structure things in a more folder like structure in your documentation Hub. But how you model your specification document is limited to how the OpenAPI specification is structured

Sorry, i didn’t really understand what you mean. what’s the difference between DOCUMENTATION Hub and MODELING?

I noticed that TRAITS has disappeared from the new version which i think is unfortunate. I know we can create a Tag that will be used to group operations in Documentation, but it’s bad that it doesn’t group them in Design mode. please have a look at the attached image, it would have been great to have a Group named “Support” in Design mode just like Restlet does (attached img)

In the previous version, you had different colors for response code 200 or 400… Hope you’ll consider start using them again in the new version.

Thanks


(Taylor Barnett) #7

Initially, it was called Next while it was in beta, but then it kind of stuck and was helpful to differentiate.

Sometimes the “base” model is more like a partial model. So in this case, shouldn’t be everything you might have on the User.

For example, in the Todos API we have in every new project. Todo partial model object includes name and completed. Then it is referenced in the Todo Full with a lot of other properties.

You might have a User partial with email, then reference it in other models such as User signin model or User contact model, which would reference the User partial but also include properties for fname and lname as required properties.

Think of the partial model as only containing the required properties for every endpoint that will use that model. You can still create a User full model with all potential properties, but it wouldn’t be helpful to use on certain endpoints that would require some of its optional properties.

Hopefully that makes sense. I’m happy to create some of the models in your project if you have the endpoints setup if you need to visualize it further.

Modeling is describing your API using the OpenAPI Specification, while a Documentation Hub is designing how your publish documentation will look like. You have the option of just publishing your API specification or doing more customization alongside other documentation. The link for documentation I shared can explain further.

Yes, sadly traits aren’t valid OAS spec, and we wanted to make sure people were creating valid specification documents that could be used with any tool.

On the last two, we will be changing how some of that looks soon and I’ll make sure to pass along the feedback.


(Reda) #8

Thank you for your explanation regarding the Models. What your recommended is exactly what we do, but i was just wondering if we can avoid duplication 100%…

OK, that’s a good example to talk about. Let’s say i created the Models you mentioned, I also need to crate a new Model User signup which will also include properties for fname and lname as required.
Here I have a duplication of fname and `lname``
What would be the best way to avoid this duplication?

The best thing would have been to create a Model User full that contains all the potential properties. And when creating an endpoint for Sign In for example, to be able to use and chose single property from the Model User full

Hope you better understand me by now.


(Taylor Barnett) #9

There’s no way to avoid the duplication in this case if you want accurate data models.

Yes, you could create a User full and only mark email are required but then when you use that data model on other endpoints that require other properties along with email, you will not be able to mark them as required since you marked it as optional in User full. But this would then cause inaccurate documentation and testing. There’s no way to modify it for an endpoint, you’d need a different data model.


(Reda) #10

Fair enough, thank your very much for your reply :slight_smile:

i’m now using only Stoplight Next, migrated all data from the old version and have 0 error/ warning!

I’d like to ask you 3 new questions please:

1- Before with TRAITS, i could have predefined headers when I create new endpoint, is there a way to do so with Next?

2- also, is it possible to have default error responses (400, 429) for each new endpoint?

3- is the field operation ID required? and what is it really for? can’t it be automatically filled just like ‘Slug’ in the old version?

Thanks a lot


(Taylor Barnett) #11

Awesome!

For 1 and 2, you can have shared parameters (which can be a header) and responses: https://docs.stoplight.io/modeling/modeling-with-openapi/shared-parameters-and-responses Would this work?

For 3, in the OAS spec, it says:

Unique string used to identify the operation. The id MUST be unique among all operations described in the API. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is recommended to follow common programming naming conventions.

It doesn’t really surface much in the docs, but it is a good practice to give it a unique name that describes the operation (GET, DELETE, PUT, etc) and what it does.


(Reda) #12

Thank you again Taylor for your reply.

Actually i know this and I’m already using the shared parameters. But what I was asking is if it’s possible to attach for example specific shared responses for every new endpoint, something similar to TRAITS in the old version.
So when i create a new endpoint, there will be automatically some shared responses in this new endpoint.

3- apparently if I don’t fill it up, it comes up in the warnings, will it be possible to auto-fill it based on the Path of the endpoint?

4- when creating a property which is an array of objects, is it possible to specify that this property can be an empty array? not null! i didn’t see how i can achieve this

5- maybe other people already mentioned this, when on “Read” view, the description of properties is in a much bigger font size, is that on purpose?

Thanks and have a lovely weekend


(Taylor Barnett) #13

On the first one, there is sadly no way of having it automatically have some shared responses right now.

On 5, that is probably a weird UI decision that could be improved. I’ll make a note of it.

I’ll have to get back to you on the rest of these.


(Reda) #14

Hi Taylor, hope you had a great weekend :slight_smile:

Just would like to know if you had any news regarding questions #3 & #4 ?

Thanks a lot :slight_smile:


(Taylor Barnett) #15

I don’t believe there is a way to autocomplete this.

If you click on the validations for that property, you can set the minItems to 0.


(Reda) #16

OK, thank you very much :slight_smile:

I have here a little list of some features that would be great if you could integrate them in a future updates.

1- the possibility to autofill the field operation ID, by using the HTTP method (POST, GET, DELETE) and append it with the path name

2- the possibility to be able to duplicate an endpoint to prevent entering again and again all the headers and error responses…

3- I dont know why, but when I add a third header, I can’t make it required (attached img), is that a bug?

4- to be able to change the order of properties through the UI, for now i do it manually from Raw Schema

5- maybe you could add a new property type which is price, it will be very helpful when generating examples

6- the possibility to be able to drag and drop any endpoint from a specific folder to another. For example i have already an endpoint /account/info in GET method, then i created the same in POST, but then i realized that i made a mistake and should be /account/info/url, I can’t edit it to change it, and if I do, even the first endpoint /account/info will change…

is any of these on your roadmap?

Cheers


(Taylor Barnett) #17

I’m going to group a few of these together in the same answer. Right now, there isn’t much autofill capability, but if you want to move or duplicate parts we recommend using copy and paste in the Code section. This is especially helpful for duplication.

There are some UI updates being worked on now that will help improve the experience on things like 2, 4, and 6.

I am having trouble replicating 3 without using references. Do it only do this when you reference?

For 5, the data types are based on the specification: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#data-types. I can though add in a feature request to make it so the number validation treats it more like a price.

In the future, if you have a feature request, I recommend opening up a topic for each feature in the Feedback section of this forum. It will help us track it better and add updates as they come.


(Reda) #18

OK great, thank you very much for your help

for #3, my colleague explained me something else, i’ll write you later with more details…