serverless-openapi-documenter adaptation

[gdlin]

Hello,

I've found this plugin and wanted to pitch in by migrating it to work with serverless-openapi-documenter. The following changes were tested with serverless 2.x, node 16 and npm 8.5.

Plugin modifications

• I've Replaced the dependencies and places where @conqa/serverless-openapi-documentation was mentioned to serverless-openapi-documenter.
• EnrichMethodsInfo was not finding the methods, I've modified the code to look for it in the correct way for the new plugin.
• The service name is included by default in the schema by serverless-openapi-documenter, so I've removed the part that appended the project's title to them.

---

Test Modifications

• Modified the tests to comply with the new plugin
• All the response docs must have a responseModel. I've created a mock for the DELETE endpoints, since the tests were failing. Either the user defines documentation: ~ or the plugin will autogenerate the mock. You might want to change the text or the mock itself, I'll leave it in your hands.
• I've mocked the UUID library for the DELETE test since the mocked schema is generated on the fly and it provides a UUID for it. Maybe you want to change it to a static name definition and avoid mocking. I've tried but it wasn't as simple as it seemed, at least for me.
• The naming of expectedOutput and actualOutput was reversed.
• AllowEmptyValue must be defined in order to be included in the output. I've updated the tests.
• Modified the expected test results order (i.e., description, title, operationId, etc)
• Updated various quirks in the expected YAML files. Mainly certain types being outputted inline and vice-versa. Others like type: null replaced for nullable: true and certain parameters that were required such as empty descriptions if there is no description.
• When no headers are defined, serverless-openapi-documenter outputs owaspHeaders or corsHeaders. When they are both empty, it outputs headers: {}. Updated the expected files accordingly.

---

One thing I wasn't able to fix is that in the full test, there is an interface that is recursive. That is generating errors for a Circular Dependency, in the Converter. The conflicting code in the api.d.ts file is:

interface ObjectType {
    types?: string[];
    children?: ObjectType[];
}

I've updated it to a string and it will pass all tests. Fixing this takes too much time that I don't really have at this moment, to be honest, I'm not exactly sure where the problem is and I can't seem to debug it easily.

Another thought, when validating the outputted schema with the online Swagger editor, it pointed out that there is no version parameter in the document. I don't think this is a problem with this plugin, but maybe check that if you can.

---

NOTE: The pnpm lock file was not updated since I don't use it myself. I tried updating it, but it was a newer version and the changes were too many.

[gdlin]

Hey, sorry for spamming; maybe you can take a look into this? It seems pretty straight forward but I need some help to fix that test and use this. Thanks !!

@roni-frantchi @Yossi-kerner @HeverFarber @omry-hay

[vadymhimself]

Hey @gdlin, is your fork up to date? If so, can you make a sample hello world application and show how it works end to end?

[gdlin]

Hey @gdlin, is your fork up to date? If so, can you make a sample hello world application and show how it works end to end?

It's working with serverless v2.73. I haven't tried it with v3 since I don't have the time at the moment. The tests were updated as well.

I currently don't have much time available to create the hello world but I'll try to make something in the upcoming weeks.