[Feature]: upload documentation to AWS

[JaredCE]

The Serveless AWS Documentation plugin is now deprecated: https://github.com/deliveryhero/serverless-aws-documentation

However, many people want to store the documentation they've generated on AWS API gateway. Now that this plugin is relatively stable, perhaps I should look at stealing parts from the above plugin so that the generated documentation is uploaded to AWS API Gateway.

[langaads]

Thank you for the amazing work in this project and for helping documentation being less of a burden. I came across this plugin looking exactly for this kind of feature.

I know this is not exactly what you are trying to achieve, but here is my use case:

My ideal approach would be able to define 'openapi frist' templates that i can reference in serverless. Serverless would then decompose and attach that documentation to each apigateway resource. When exporting documentation via apigateway i would expect the output to be similar to the initial openapi template. Since i use multiple micro-services under the same api, i could define their docs separately, and apigateway would generate a unified version in the end.

What you are proposing solves the second and most important part of my goal, as my client insists on using aws-sam because of the openapi-first approach it supports.

I am willing to contribute.

[JaredCE]

Hey @langaads

So I need to start thinking about this again...

Always happy for people to raise PR's to help out with this project.

I think i might be misunderstanding, you're not using serverless to deply your API gateway definitions? I was thinking that i would use an after-deploy hook to upload the openAPI defintion to AWS API Gateway. Though vaguely looking through the documentation for uploading documentation, it seems a bit trickeier than i thought.

[langaads]

I'm still studying the internals but so far i think there are 2 ways to achieve this:

1 - By generating the resource "AWS::Serverless::Api" "DefinitionBody" property to attach an openapi collection to the api, this would be a good approach if you have a decoupled openapi doc somewhere in your project and want to use it. It would make sense in projects where each serverless template have it's own API.

2 - By generating the "AWS::ApiGateway::DocumentationPart" for a fine grained documentation, so each function would have it's own documentation part. This approach would make documentation a little more coupled to serverless but would make sense in a scenario where multiple serverless templates are reusing the same API.

[JaredCE]

So vaguely looking at them, I'd suggest we need a new library that can generate the x-aws- parts for any given openAPI file in whichever specific style. For the needs of this particular plugin, i think i need the AWS::ApiGateway::DocumentationPart x-aws- added to the end result openAPI document before uploading to API Gateway.

For your own requirements it sounds like you need the AWS::Serverless::Api" "DefinitionBody" with it's various x-aws- additions generated for the openAPI document.

[langaads]

For my requirement it would make sense to use DocumentationPart as well because AWS::Serverless::Api" "DefinitionBody" assumes i have an openapi collection for the whole API Gateway, which i don't. I only have pieces of documentation for each service under it.

So far it looks like DocumentationPart would solve most common usecases, and i think the way it's designed you are not required to have an openapi document attached to it, it's just the way apigateway was documented before openapi was even a thing.

the tags x-aws-... would only be necessary if the doc is uploaded via AWS::Serverless::Api" "DefinitionBody"

I'm just making some assumptions, this needs to be tested.

[JaredCE]

Right so I started a project here: https://github.com/JaredCE/OpenAPI-AWS-Decorator

I need to merge the branch to main, then start messing about with trying to upload the augmented openAPI document. I don't run my own personal Serverless/API Gateway/AWS stuff, so i'll probably have to mess about on my work one.

I haven't tried doing the model documentation... that looks a bit... tricky? like you have to document each property of a model e.g.

{
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    },
    "errorCode": {
       "type": "number"
     }
  } 
}

You need to create a DocumentationPart for error and errorCode... I don't know how deep that rabbit hole goes.

[langaads]

Localstack have a good apigateway coverage, perhaps adding a dev-container to this project with a localstack might be enough for manual and e2e testing.

[JaredCE]

Ok, so i'm getting there.

So i'm uploading the DocumentPart augmented OpenAPI straight to AWS from the CLI. But i'm struggling to get it to generate the correct openAPI document when i publish and try to export the documentation from API gateway.

You can see the issue here: https://stackoverflow.com/questions/76549989/how-do-you-assign-requestmodels-to-a-method-aws-api-gateway-documentation-part

@langaads I wonder if you have any experience with this and can see anything i'm obviously doing wrong.

[langaads]

Sorry for the hiatus @JaredCE i disconnected during my vacations.

My knowledge around DocumentPart is purely theoretical, we are probably on the same level.

I never used it myself in real projects for the same reasons you are having trouble. It's documentation is poor and it's a burden to document things twice, hence why your library would be a game changer. I wouldn't be surprised if the issue is just an incomplete implementation on AWS's end.

Let me do some research as well.