Automatic Documentation - Generate Swagger UI from your Serverless Config
HTML-код
- Опубликовано: 8 ноя 2021
- If you want to automatically generate documentation for your serverless project then you can use the "serverless-auto-swagger" to do just that.
`npm install -D serverless-auto-swagger`
If you want to have a text based version of this article then you can read it here.
www.completecloudarchitects.c...
If you want to look at the underlying code, want to submit a bug or issue, or even want to contribute then the link to the github is here:
github.com/SamWSoftware/serve... 
Наука
In case the plugin deploys Swagger UI at a different host than your application's one. I figured out how to make the plugin deploy Swagger UI at the same host as your application. You most likely want to add apiType: 'http' to the plugin configuration section. It works for me. Additionally, don't forget to add basePath if you use a custom stage. Please rate the comment, so everyone else can see the possible solution for their headache.
You can share your solution on stackoverflow
very helpful
Awesome! I have question.
How can I specify the "Example Value" without using the default value of type??
Hi Sam great plugin!
But i am having a little issue here when I created a type file I tried to extend a class into a Interface but doesnt seems to work am I missing something?
From Mexico, you are the goat
thank you. I wanst understanding how to specify bodyType until your explanation
thanks you for your support my friend
Thanks for watching and commenting on the videos. It really does help
Thanks for the introduction to this Plugin Sam. Could you share an example where GET call with Query Params is also present - as of now its mostly GET with path params and POST calls. :) :) You are doing an awesome job there, so much to learn.
I think there are some examples using query strings in the docs of the plugin
Hi Sam! At the moment of deploy, the swagger documentation is deployed in a different API Gateway because add *dev-{service-name}* exist some way for delete the stage before *{service-name}*
Amazing work Sam! I Been looking for a solution for API documentation.
It's something that I've thought about for ages. Why define your api once for serverless and repeat yourself for documentation
@@CompleteCoding Yup! Anyway, I realised that there is no link to your github repo for the code on NPM, could you list your github repo there incase anyone wants to open issues or get help? Thanks
Just added the link to the video description
github.com/SamWSoftware/serverless-auto-swagger
Thanks man, you save my life!
Glad to hear that!
Great work Sam.. Really Helpful.
I have one question: will it identify query parameters of the request?
That's a really good question. At the moment it doesn't but that is definitely a feature I could add.
Would you think it better to do it like this
{
path: '...',
queryParameter: ApiQueryParamType
}
or something else?
@@CompleteCoding Hey Sam, I can see you added that .. Great
@@febinr8888 I've already added that to the plugin. If you read the readme there are instructions on how to add query string details
Amazing! Thank you!
Glad you liked it!
Hello Sam ! Thanks you for your job.
Is there a way to exclude endpoints, or specify only some endpoints ?
Not at the moment. Adding that functionality wouldn't be too hard. It would just mean adding an optional parameter to each event for exclude. In the plugin logic, when creating an 'endpoint' you just filter on ones that are excluded.
I've added an issue to the repo. You could look at adding that functionality to the repo if you want to.
@@CompleteCoding Thanks a lot !
love this plugin but i miss some implementation using the serverless-openapi-documentation format,
Nice plugin, excellent work! Does the plugin work with serverless framework 2.0? Also is there a way to hide the API documentation based on the stage - for example the API documentation should be available in non prod but should be hidden in prod to avoid exposing proprietary information to public.
yes it works with framework v2.
Currently not but that would be a really cool feature. I'll add it as a feature request to the repo. If you want to try and implement it then that would be amazing.
Hello, I'm trying to use the bodyType with an interface that extends properties from another interface. When swagger is loaded the model is not showing the proprieties from the extended interface. There's a way to fix this?
Thank you for this npm package! A quick question on C# based Lambda implementations, are there any special requirements for using this npm package? Will it work the way you demoed in the video? Thanks again!
The plugin shouldn't care how you've written your code. The only thing you'll not be able to do is use the type definitions to define your body in requests and responses
That is magic! Thanks.
Glad you like it!
Hi,
I tried auto-swagger with serverless-esbuild and they are working as you mentioned in a comment. Thanks for that.
Could you please provide option not to deploy, so that we deploy the generated swagger files using our serverless.yml, which will deploy the docs in same url as our app and we can do Try-it-out in swagger page. Please correct me if i am wrong.
Thank you very much for the video, one question, can this plugin generate the same file for two different paths where one shows only certain functions? I appreciate any information
So generate two separate swagger files - eg one for internal docs and one for external (which hides some endpoints)?
Not at the moment. You could add it as a feature request though
Hello, great work. The pluging can manage function versions? It just works with serverless offline o it can be uploaded to s3? Thank you.
The serverless framework manages the function versions. The plugin just generates the documentation.
You could deploy the swagger config to S3, but the plugin deploys the swagger docs url with the rest of your APIs.
Hi Sam!
Tons of thanks for the video.
I want to ask a question. Would be so greatful if you could answer it.
I want to pass origin from header parameters in api but swager url is overriding the origin. Is there any way to pass different origin in header?
Do you mean in the swagger UI when testing the API endpoint?
@@CompleteCoding yes
for more example: i have one api get-roles... and on the basis of the origin i am fetching roles.... now in this scenario what is happening.. when i testing api from swaggerUI the origin will always be the swagger one.. so not able to do the testing
@@mahimajain9133 That would be a feature for swagger-UI it's self.
Hello Sam!
Can you add option to include context path in 'try it out' ?, the stage context path is missing ('dev') in the api path, hence it results in error
I've looked into updating the package to get the 'try-it-out' to work.
The challenge isn't with localhost but when it gets deployed. The plugin somehow needs to know the url of the API before it's deployed.
@@CompleteCoding
Would be okey to concat the stage in generatePaths() (ServerlessAutoSwagger.ts:273) ?
I'd like to try that but I don't know how.
Thanks you for your job!
Do you have the source code for the project you ended up with? I have tried using the aws-nodejs-typescript starter, but it looks very different to your code. It seems to now use serverless-esbuild instead of serverless-webpack. Does serverless-auto-swagger work with serverless-esbuild?
I've not tried it yet but it should do.
The serverless-auto-swagger hooks into the serverless framework before it gets to compile
Awesome... I have a question, I have my end-points generated with /dev in the basepath as the dev stage when I run serverless locally. The swagger is getting generated, but the /dev is not getting appended in the URL, when I try try out, I'm getting 404 error. Request your help on this.
The stage should be getting added to the url path.
Are you using http or httpAPI endpoints?
@@CompleteCoding Im using http end-points
Can you please share sample code
Also, the swagger folder is getting created outside my src folder, so the sls deploy command is failing to deploy the generated swagger folder.
I'm getting below error when trying to serverless offline start
TypeError: _a.defineFunctionEventProperties is not a function
Hi Sam,
When I set the responses object in http event function i'm receiving an error 500 (TypeError: Cannot destructure property 'responseParameters' of 'chosenResponse' as it is undefined.Ï)
when I try the endpoint in both postman and swagger.
When I comment the object the endpoint works.
Thanks in advance!
Try to use responseData field instead of responses, it helps me
@@dimakozoliy2248 It works! Thank you so much!
great content
Thanks
Awesome!!!
Glad you liked it
Good content
Thanks
Hello Sam,
I am trying to use serverless-auto-swagger along with serverless-bundle for a nodejs project. serverless-bundle seems to expect ES6 export import syntax, but the swagger src created are having commonJS require() syntax..could you pls guide me how can i use serverless-auto-swagger along with server-bundle plugin ?Im getting the follow error:
swagger-json.js
1:1 error 'use strict' is unnecessary inside of modules strict
2:1 error Definition for rule '@typescript-eslint/no-var-requires' was not found @typescript-eslint/no-var-requires
Hey, did you found a solution to this?
Hey, Sam! For some reason my SwaggerUI and SwaggerJSON function names are returning undefined when deploying to AWS. Do you know why it can possibly happen?
I'm not sure. If you add an issue to the github project then we now have a group of us working to improve it
Hi Sam,
Thanks for the amazing content I just joined the project that is using serverless framework and your channel is my one stop destination for every problem.
Now, I am struggling with passing array, string, date ... data types via bodyType to request body or response body. Is there any way of doing it. if yes please let me know. Thanks.
Super glad that my videos are helping you out.
You have to pass the name of the typescript interface into bodyType. That could be as simple as
type postRequestBody = String
if you want them just to post up a string in the body.
@@CompleteCoding Thank you so much Sam . Can you please also guide if we somehow can use date data type as well?
@@mahimajain9133 The only data types supported by swagger are string, number, int, boolean, array and object
you'd have to specify that they send either a string (Wed Apr 06 2022 10:44:56 GMT+0200)
Or a number (1649234680333) which is just the timestamp.
Hello Sam, excellent work and content.
Question: Your awesome plugin also will work if I use the standard "serverless.yml" file ? or is only compatible with the typeScript implementation ?
Thanks 😊
It'll work exactly the same with a serverless.yml file.
@@CompleteCoding Thanks Sam
@@CompleteCoding And what about if I have the standard "serverless.yml" file and also I am not using TypeScript ? I ask because i'm using NodeJs and got this error "Error: ENOENT: no such file or directory, open './src/types/api-types.d.ts': unable to get types"
@@dorianyeye Nice spot. I'll have to fix that. For now if you add an empty file to /src/types/api-types.d.ts` then everything should work.
Is there a way to agroup endpoints under a controller group? I was implementing it here and all endpoints got clustered in a single group, without separation by entity.
Thank you for the plugin!
Just found it, using swaggerTags, thank you for your work!
Hi, Sam, It is really amazing and super convenient plugin. Thank you!
I am implementing auto-swagger to TypeScript Lambda project with serverless-esbuild and it creates its own host not connected to my end points. When I tried to use host property config it throw error on deploy as unrecognized. Try to search and google with no result. May be you can advise? thanks a lot in advance
Look at Pavel Razuvalau reply!
Can I use it in a JS projetct? How can I specify .js models?
Hi Sam!
This plugin was deprecated? I didn't see updates on npm...
Does this support 'serverless-http' for having `/{proxy}` functions to be read from the express router?
It wouldn't be able to pull the paths from express. It gets all of the path data from the serverless config.
can you please share the github version of this project - also a video on serverless frameworkversion 3 migration is much needed, as the documentation sucks.
Is that possible to generate two different Open API files? Like Internal OpenAPI and Partners OpenAPI?
That would be a new feature request for the plugin.
It would have to add a way to define which docs to add each endpoint to.
Hello Sam, Nice Plugin!
But I can't able to deploy to multiple environment, every time it is deploying to dev only. I'm getting Error:
CREATE_FAILED: SwaggerJSONLambdaFunction (AWS::Lambda::Function)
XXX-dev-swagger-json already exists in stack. Can you please help me!!
I am getting this error
Failure: Cannot assign to read only property 'exports' of object '#'
Can anybody resolve this?
Is there any one who has solved error at production level i am struggling with statusCode 406 please help.
Hi Sam, there are some modules that I want to ommit in the documentation, how can I do this?
The plugin currently adds all interfaces in the provided type files to the docs.
The easiest way to exclude some interfaces is to have one type file that exports interfaces you want in your documentation and one with all the types that you don't. Then just tell the plugin to only look at the first file.
@@CompleteCoding Hey. sam. After my deploy I get this sls error " Missing required key 'FunctionName' in params" and it breaks my pipeline, do you know how to solve it?
@@danielcarvalho8153 I don't think that is coming from my plugin. I searched the repo for `Missing required key` and found nothing.
Does it appear to be breaking in the auto-swagger part?
@@CompleteCoding I don't know, too. I imagine it's caused because the name of swagger's lambdas which the plugin creates comes like this. '' swaggerUI: undefined". But I don't know if there is a way to solve it. But no problems, Sam. I total appreciate your answers.
What if i have created a swagger.yml file myself and want to get a swagger ui of that without auto generating?
Then just create a swagger endpoint that imports your existing swagger file. No need to use the plugin. There are loads of code examples of creating a swagger endpoint.
@@CompleteCoding yeah did that , thanks for the reply
I am getting like this No operations defined in spec!
which VS Code Theme are you using?
Monocai Pro. It $10 but so worth it. I used to switch themes every few weeks but had this one for almost 2 years now
@@CompleteCoding thank you!
Tinku Jiya
Hi sam,
How can we pass path parameters from swagger?
Yes, Check out the documentation. You can add path params, query params and more
@@CompleteCoding I only found queryStringParameters and headerParameters. Is there any way to add a path param? Btw. great job!
@@michalzawitowski2518 same here
@@mahimajain9133 Im able to present path params only by duplicating path in
parameters:
path: hello/{helloId}
What probably is a bug?
@@michalzawitowski2518 ya probably it is coded to work this way only though its working for me as well thanks for sharing.
hi...how do i set my body properties
on each event you can add a "bodyType" parameter which points at your typescript type.
http: {
path: 'hello',
method: 'post',
cors: true,
bodyType: 'helloPostBody',
}
@@CompleteCoding I get the error "bodyType" is not a property
P.S: I am not using Typescript
@@opehardesina Are you using something like ES Lint or something similar?
bodyType is not normally a property of an event, but when using the plugin it should be available.
@@CompleteCoding No i'm not but for some reason i get that error
why people don't use apidoc and they prefer swagger? weird
Swagger has been around for a very long time and is what a lot of people are used to. I've never heard of apiDoc but it looks like it could be used in a similar way.
It does look like you have to comment your code in a particular way to get it to work. That means there are two places you're now defining what your path looks like, making it just as likely to become out of sync. This plugin generates the swagger from your API config so you only define it in one place
this doesn't work anymore
Since releasing the video there have been LOADS of changes to the npm package
@@CompleteCoding yeah, that's why. is there any fixes?
Thanks Sam for the nice plugin. That is very useful.
Getting validation error on bodyType,
Configuration error:
at 'functions.hello.events[0].http': unrecognized property 'bodyType'
I've had this pointed out. I'm looking into fixing it in the next release
Are you using typescript, ES Lint or anything like that? Also what IDE are you using?
@@CompleteCoding To reproduce it, in serverless.yml, set configValidationMode: error; I will get the above error doing sls generate-swagger. Thanks for looking into it.
I am getting Couldn't read types from file: ./src/types/api-types.d.ts.Dont know why
You must create "api-types.d.ts" file in your local folder src/type, otherwise, you can also use another file for types using the config param "typefiles"