Reverting to previously used documentation returns wrong documentation

[tommy5dollar]

Hey,

I'm having an issue where if you change your documentation from an initial state to a new state and then back to the initial state then the documentation parts on the API Gateway (and the Swagger) will be from the new state, not the initial state, despite the initial state being the current documentation.

You should be able to recreate this issue by making any simple change, even one as simple as adding a word to a title/description/summary, deploying and then removing that word (so the documentation is the same as before) and then redeploying.

It seems this is because serverless-aws-documentation only checks that a documentation version already exists (and if it does then it bails out of the rest of the process), rather than ensuring that that documentation version is what is current for the API/stage.

I can see a couple of potential fixes, although they all seem to have issues/limitations:

• When deploying, check not only that the current version exists but also that it is the current version on the stage. If not then set the current version on the stage to the current documentation version. This would fix the Swagger output from the stage but wouldn't correct the documentation on the API itself.

• When deploying a new version of documentation, delete any old documentation versions. Therefore, when you revert to the old documentation it'll view it as new documentation and add it correctly. This obviously breaks any usage of documentation history. I'm not sure if this is an actual issue or not?

I'm happy to write a pull request for either of these approaches if we manage to settle on which action is the most appropriate.

Thanks in advance.

[kamzil]

I also ran into this issue when preparing to use this plugin in our project. If I at some point make changes to the documentation, I can never use the old version through this plugin, even if I make many changes in between. It just says "documentation version already exists, skipping upload".

@tommy5dollar did you find a workaround for this?

[tommy5dollar]

@kamzil I honestly can't remember, to be honest.

We're no longer using the documentation plugin as we've moved to GraphQL

[madzim]

@kamzil I figured it out.

You need to update custom.documentation.version to a unique value. It can't be a value that is already in the Stages | Document History tab.

The new version is automatically published and you'll see the changes the next time you export the API.