serverless-aws-documentation icon indicating copy to clipboard operation
serverless-aws-documentation copied to clipboard

Skip all Documentation Parts overwriting in case of shared API Gateway usage.

Open YurgenUA opened this issue 5 years ago • 11 comments

tackling this problem: https://github.com/deliveryhero/serverless-aws-documentation/issues/106.

As of today plugin removes all doc-parts before deploying modified changed documentation. While this approach works ok in majority cases, it fails when API Gateway instance is reused by many sls deployments (and this scheme is more frequent approach as developers build more complicated APIs). This PR introduce a piece of functionality which helped me to keep up with API documentation functionality having roughly dozen individual serverless.yml deploying under one API Gateway.

New function _isSharedApi() uses serverless.yml information to return if API is being deployed is in standalone mode (which are any deployment so far, since plugin correctly refreshed Documentation for that cases) or uses (shares) pre-existing API Gateway per https://serverless.com/framework/docs/providers/aws/events/apigateway#share-api-gateway-and-api-resources.

If deploying API is standalone, execution logic stays the same, i.e. all doc-parts removed and than recreated from deployment. If deploying API is shared, only those doc-parts which belongs to current service (new property 'serverless-service' saved with each doc-part) removed and recreated. Thus, all other doc-parts, belonging to main service, or other dependent services are left untouched.

YurgenUA avatar Aug 19 '19 19:08 YurgenUA

Codecov Report

Merging #121 into master will not change coverage. The diff coverage is 100%.

Impacted file tree graph

@@          Coverage Diff          @@
##           master   #121   +/-   ##
=====================================
  Coverage     100%   100%           
=====================================
  Files           8      8           
  Lines         437    453   +16     
  Branches       60     63    +3     
=====================================
+ Hits          437    453   +16
Impacted Files Coverage Δ
src/documentation.js 100% <100%> (ø) :arrow_up:
src/models.spec.js 100% <0%> (ø) :arrow_up:
src/downloadDocumentation.spec.js 100% <0%> (ø) :arrow_up:
src/downloadDocumentation.js 100% <0%> (ø) :arrow_up:

Continue to review full report at Codecov.

Legend - Click here to learn more Δ = absolute <relative> (impact), ø = not affected, ? = missing data Powered by Codecov. Last update 78a81be...d3c6373. Read the comment docs.

codecov-io avatar Aug 19 '19 19:08 codecov-io

Hey @YurgenUA, thanks for contributing! Can you add tests for this one please? Then I can merge it

tchock avatar Nov 12 '19 17:11 tchock

@tchock I added unit test to invoke code changes and return coverage to 100% back. Hope PR is possible to merge.... we use this in our production for couple months without problem.

YurgenUA avatar Nov 20 '19 09:11 YurgenUA

Any plans of merging this?

AYM1607 avatar Jan 07 '20 18:01 AYM1607

@tchock Can you please merge it and release a new version?

PatrykMilewski avatar Jan 20 '20 09:01 PatrykMilewski

If anyone is interested, the workaround is to clone repo with pull request and provide it as local serverless plugin, more details here: https://serverless.com/framework/docs/providers/aws/guide/plugins#service-local-plugin

PatrykMilewski avatar Feb 04 '20 08:02 PatrykMilewski

Another possible workaround is to reference git repository directly in project.json, like

"serverless-aws-documentation": "https://github.com/YurgenUA/serverless-aws-documentation.git",

both npm & yarn support it. Even specific git commit can be specified

YurgenUA avatar May 14 '20 07:05 YurgenUA

@tchock I am also now using this fork and it would be great if this could be merged! Thanks @YurgenUA for the great work, this saved my day :)

gcampionpae avatar May 26 '20 14:05 gcampionpae

Hi! We at Delivery Hero are not longer using this plugin.

Willing to hand it over to someone who is willing to carry the torch.

sime avatar May 26 '20 14:05 sime

HI @sime If I can ask, what did you switch to?

gcampionpae avatar May 27 '20 07:05 gcampionpae

Our swagger is now auto generated from our application.

https://docs.nestjs.com/recipes/swagger#openapi-swagger

sime avatar May 27 '20 09:05 sime