Creating / branching a new version


(Robert) #1

Our current version of our API is 3.8.4.

We’re getting ready to release 3.8.7. How should I do that?

I have a new swagger.json so my thought was to start by duplicating the existing project, but I can’t see how / where to do that.


(Erik Hansen) #2

You can use Stoplight versioning within the same project https://docs.stoplight.io/platform/versioning/versions
When you “release” more than one version, you published hub will have a version selector at the top of the page where you can select which version of the hub is shown.

However, since you are only incrementing the PATCH version (https://semver.org/) you may want to only have the latest version of docs “released” since you should not have made any breaking changes in your API.


(Robert) #3

Is it possible to create an alias so striim384.docs.stoplight.io points to striim.docs.stoplight.io?

We need both versions since customers running 3.8.4-3.8.6 won’t have back-end support for the 3.8.7 API.


(Taylor Barnett) #4

Alternative idea:

You create a seperate OAS file for 3.8.7 and link it in the header. (And also have a clear link for the older version too.) I know it is less than ideal since our versioning doesn’t have patch versions, but this way it can still be in all one documentation URL.


(Robert) #5

Is it possible to just copy the existing project?


(Taylor Barnett) #6

Just to clarify, so that it would be different Hub files?

In the way, I suggested, I am imagining them in the same Hub file.


(Robert) #7

Different. The most efficient thing for me at this point would be to copy the existing project and replace the JSON.


(Taylor Barnett) #8

Could you do that if you copy the OAS file and make a new one for the different version in the same project and Hub file?


(Taylor Barnett) #9

I can build a quick example of what I am thinking if you want me to.


(Robert) #10

What would the URL be?

And we need to hide the beta version until 3.8.7 ships.


(Taylor Barnett) #11

Just built an example: https://robert-example.docs.stoplight.io/

You see the two API references I created as header links. They are separate OAS files in one project. You can remove the link to 3.8.7 until it ships.


(Taylor Barnett) #12

Hey @robert! Just wanted to check in on if this would work for you.


(Robert) #13

I’ve been in release mode, updating the API is next on the list after we ship.


(Taylor Barnett) #14

Sounds good! I’ll leave the example up then.


(Robert) #15

That looks OK but it doesn’t give me any idea of how to do it.

Also, the existing docs must either stay at striim384.docs.stoplight.io (since online help and PDFs for versions 3.8.4-38.6 tell customers that that’s where they are) or that URL must redirect to striim.docs.stoplight.io.


(Taylor Barnett) #16

Setting a redirect to a different URL is definitely possible because in the publishing settings you can add 301 redirects to a page in your Hub or an external website. In this case, it would be an external website.

In your old docs, you published your OAS file. In the example, I created I made a Hub and then create pages that reference an OAS document, one for each version.

Then I added those pages as header links in the Hub Settings.


(Taylor Barnett) #17

Does that help any @robert? I’m happy to expand more.


(Robert) #18

We just shipped so I’m finally getting around to this today.


(Robert) #19

@taylor can you please give me the code for that hub? I’m completely baffled by the UI.


(Taylor Barnett) #20

Totally. I’m going to send you a private message so you could send me what project you want me to create the Hub in.