Building Microservices with Go: 7 Documenting RESTful APIs with Swagger

[@NicJackson]

Hi folks, there have been a few issues with Windows and the instructions I provide in the Video. The Makefiles I am using were created for Go 1.13.x and Linux / Mac. As such there area a few inconsistencies between the different platforms, a cross platform approach for Windows in command prompt or powershell and Linux / Mac can be found below. I have also updated the README on the repo to reflect these options. So for generating the Swagger, you need to install the Swagger CLI, this is a one time operation and can be done with the following command: go get -u github.com/go-swagger/go-swagger/cmd/swagger Then you can generate the Swagger documentation: swagger generate spec -o ./swagger.yaml --scan-models Once you have that run the server , windows will prompt you to add a firewall exception, click ok: go run main.go To get the documentation you should be able to do: curl localhost:9090/swagger.yaml Or open the following link in your browser: localhost:9090/docs

[@thovinh5386]

It gave me this after I run `go get ...` swagger : The term 'swagger' is not recognized as the name of a cmdlet... The Internet says something about the GOBIN but I don't really understand what they are talking about. PS: In the end, I clone the entire go-swagger repo to the building-microservice-youtubes folder and call directly go run .\go-swagger-0.25.0\cmd\swagger\swagger.go generate spec -o ./swagger.yaml --scan-models It runs but it doesn't give me the expected result. PSS: Swagger seems too good to skip so I might as well move to Ubuntu and setup the environment there.

[@thovinh5386]

Why does my swagger generate an empty spec .yaml file? "One thing I noticed about Swagger it is very specific about the way the whitespace parses. Played around for about 10minutes wondering why spec wasn't generated. Turned out there was a new line before the package declaration and no new line before function comments which caused the spec to be empty ". credits to Thanh L. Please pin his comment.

[@theskydeath]

​@@thovinh5386 Thanks. Both the comments above helped a lot. For others if you are using windows system Problem: 'swagger' is not recognized as internal... Solution: 1. set GOPATH as workspace/go in environment variable. 2. add workspace/go/bin to your path environment variable 2. copy make.bat from github.com/nicholasjackson/building-microservices-youtube/blob/episode_7/product-api/make.bat and create it in root folder of your workspace 3. run make.bat - basically, this file will download swagger cli in workspace/go and swagger.exe in workspace/go/bin. Thus making swagger know command to windows. Problem: swagger generates empty spec Solution: Be careful about your white space. specially, in this case DO NOT add blank line between // swagger:meta and package handlers statement (refer 7:55)

[@MdManik-if2er]

You can't imagine how much you have helped me.❤❤❤❤❤❤💖💖💖💖💖💕💕💕💕💕👌

[@Jeremiahhard]

As a mac user, I can't continue because swagger is not working as you did in the video

[@rauannurbatyrov7584]

Great tutorial, thank you very much. I haven't seen a better explanation for Golang. Looking forward for the next series.

[@NicJackson]

Thank you, I am positive, there are many better than me but I try. I am glad you are enjoying things.

[@vladimirdabic3927]

@@NicJackson maybe they are better, but you have the best Go series there are, trust me, I've seen a ton. You should make a course and put it on Udemy or smth, I'm certain it would be the best course out there, for sure, and I would be the first to buy it! Wish you the best and thank you for the content!

[@chriiisle]

One thing I noticed about Swagger it is very specific about the way the whitespace parses. Played around for about 10minutes wondering why spec wasn't generated. Turned out there was a new line before the package declaration and no new line before function comments which caused the spec to be empty

[@hmavani7]

90 mins before I saw your comment. I hope Nic pins this comment.!

[@UswatunHasanah-bp2fv]

Hi Tanh L, your comment save my day. Thank you very much......

[@thovinh5386]

PLEASE PIN THIS COMMENT.

[@aome15672]

Important comment, thank you much!

[@dheerajbhavsar9769]

You saved my day man. Thank you very much. Please Pin @Nic Jackson

[@bitsnbytes7514]

You make a nice point near 39:52 (being on the fence about making the documentation swagger-specific, then finally accepting it for a lack of a better solution). I haven't watched your video about data validation yet (just discovered your channel), but I'm hopeful that, at some point, Go gets mature enough so that you can describe this kind of constraints as native contracts (and -- ideally -- that Swagger eventually integrates with go contracts somehow, so that you don't have to specify the same thing twice). Anyway, you seem to have some really nice content there. Thank you so much for your insight, you definitely earned my subscription.

[@NicJackson]

I don't mind the comments to much with GoSwagger, however; I don't particularly like creating structs just for documentation. The ResponseWrapper approach is kind of ugly. I am going to play around with that to see if there is a better option.

[@LukasRotermund]

Thank you for this greate series! There is a nice "implementation first" variant of swagger called "swaggo" that fits more cleanly into the go code. This way you don't have to add all the models for the response and request parameters. All in all you have less boilerplate code for your API documentation.

[@consistentprani5034]

yeah absolutely

[@HrishikeshBajad]

If I would have found your video before, I would not have wasted 3 days on swagger. Thanks man.

[@Hmm1298-8]

Thank you nic for this series. I am so grateful, please, please, please bring more content like this. The world needs people like you!

[@changhuang8175]

Excellent go-swagger tutorial

[@hawaijarjs7496]

Another awesome learning. I like the funky music at the end. Please don't remove it 😆... As always, thank you 🙏

[@dimayasnohurskyi2805]

On Linux, if swagger shows error "unsupported type "invalid type"make: " remove in Makefile GO111MODULE=off

[@Daniel-dj7vc]

Thx

[@phdcoder6249]

Same error in MAC for some odd reason, spent 20 minutes in this.

[@thinhnguyendoan338]

Thank you very much

[@dulitharuvin17]

Hey @Nic , Great content, thank you very much for your effort to educate the community. got a question to ask, maybe Im little too late to the party :( , but hey better late than never. How did you generate the spec for the Product model struct, which is being used as an array type for the productsResponseWrapper, I tried many solutions, but none did work, I did annotated the Product model struct with swagger annotations, even though it seems like you did it off screen, the expected refs are also not generated, is there any other thing to follow to get the spec to get updated with the properties of the model struct

[@rahulisbeck]

Hi @Nic, did some of the tutorials go missing? In tutorial 6, there was only one handler (products.go) but in this tutorial, there is a separate handler for each method (get.go, post.go etc.). Is there another tutorial where we have the video of separating each handler?

[@NicJackson]

Im sorry i feel this might have been my mistake. I refactored to clean up the code but did this off camera. I learned my lesson here. Always do a refactoring video when i do that in the future

[@RH-of5cr]

@@NicJackson quite challenging to follow this episode due to the change in state, even the github code for this lesson doesn't contain some of the swaggery examples you are giving during the video... refactored from last lesson plus, I gather you refractor again at the end of this video? will skip this lesson - all in all decent series - thanks!

[@Al00Ri]

Is it common practice to organize the different HTTP verbs for an endpoint, like "products" in this example , into separate source files?

[@richarddetsch7912]

Nice job! I learned how to swag my go service.

[@UswatunHasanah-bp2fv]

Thank you very much, Nic. Your tutorial is awesome and easy to follow. Really helpful for my Golang Journey, especially for Micoservices.

[@rajeshreddy652]

Hi Nic, Thanks for the best course and Properly learning Microservices and waiting for docker classes and other topics on your list. One Quick question: If I change the swagger doc path from "/docs" to "/swagger/docs" then it is breaking (Error: "/docs" not found). can you please explain how Handle func handling the above case.

[@AlexVargas-rq7bl]

Hey, I was stuck at episode 6, when did they add those other routes and handlers? It was all within products.

[@rsvenkatesh]

Very detailed, Thank you!!

[@antoniusvanhaeren6984]

Good morning, Thanks for your tutorial. Very clear and logical. I think status code is nocontent 204 instead of 201. regards Tonny from Belgium

[@angeloskouratzinos8796]

the code seems to have been heavily refactored since episode 6 (split code in different files, Product/Products switching from being a pointer to not being one and vice versa in some functions, extra GET function and additional router definition for it) but it is not shown or explained anywhere that I can find and I'd like to know the rationale behind the decisions as well as the process for it. I understand it might be too late in the series now to do a video on it so maybe there could be an explanation in some other form? it's possible I just missed the point where it was shown/explained

[@NicJackson]

Hi Angelos, Occasionally I do this off stream, I am building this content as I go rather than deconstructing an existing project. For that reason I often look back at what I have done and find a better way to do things. I try to keep things brief and to the point in the episodes so try too avoid detail outside the current feature but I can now see this is confusing. I am going to run a stream tomorrow to do a little refactoring on the code written so far to get it in a shape better fitting for introducing bi-directional gRPC services. I will also discuss some of my rationale behind why I refactor and cover the refactoring I did in Ep 7. kzbin.info/www/bejne/imPFg31no7Ssaa8

[@angeloskouratzinos8796]

@@NicJackson thank you very much for the reply and being understanding. I'll tune into the stream, now only a couple hours away. thank you for all the knowledge you share and the effort you put in, it doesn't go unnoticed

[@milan319]

@@NicJackson Was this stream ever recorded? I mean the re-factoring stream? It was from the 25th of April but the video is just stuck on Waiting for Nic Jackson. Otherwise, I'll just take the code from this episode, it's easy enough to follow as to what was done with the refactoring.

[@AphixDev]

Nic, you are absurdly amazing!

[@mfthaking]

Thanks a lot for the tutorial, it's pretty straightforward, especially comparing to this lib documentation. I mean, the doc is pretty big and detailed, but there is no good start point or some tutorial. Thanks again!

[@Suraj-tz3oq]

I am looking to exclude a specific field from a specific api using tag/operationId. Is it even possible using any other library as well? Thanks

[@esaldinofonseca7179]

Thank you, i learned very well!

[@wolfdhib1]

The DeleteProduct instruction on the collection should be: productList = append(productList[:i], productList[i+1:]...) Otherwise, amazing course thank you.

[@jayeshthamke7860]

Hi @Nic Jackson, the tutorial is very helpful thanks, I wonder how to host the public api doc on particular domain. I appreciate your response!

[@damiencupif7894]

Thank you Nic for this series, it's really helpful. I tried adding Swagger doc generation to my own API. Question for you, I have this type which has its own custom unmarshal function. The JSON format is different from the type of the struct generated in Go... how can I handle this? :/

[@NicJackson]

So what swagger is really doing is reading the documentation from your structs. Theoretically as long the doc is on the struct correctly I would expect it to render. However depending on the complexity of the custom object you might be best defining a Request object which is a simple version of this struct and then just build an adaptor pattern. I would be happy to take a look at the code if it would help

[@damiencupif7894]

@@NicJackson Thanks for the quick answer and offering to take a look at the code. I simplified a bit but here's a link to the playground with just enough code to illustrate the essence of my question: play.golang.org/p/EmDmk02sQou. My issue is that the Quantity type is documented as being a simple float64, whereas the custom marshal function shows that the client should in fact send a structure with `unit` and `value` fields. Let me know if it's unclear. Since this quantity field is nested in a complex structure with a lot of fields, I thought I'd try to avoid redefining a type just for the sake of documenting, and use struct embedding. Could you explain me in more details what you meant by using an adaptor pattern for this usecase?

[@NicJackson]

@@damiencupif7894 Hey so I would be inclined to simplify things here, I would be inclined explicitly add unit and value to Quantity the quantity struct. If you need this converted when the struct is used then I would just implement a GetVolume() method on Quantity. You can also implement SetVolume() methods if needed. Implementing processing logic in your Marshal JSON can hide functionality. If your API objects are not suitable for consumption for upstream code, or if you want a layer of abstraction then the adaptor pattern is often used (en.wikipedia.org/wiki/Adapter_pattern). This way you have one model for the API contract and one for the application code, the adaptor pattern allows you to convert the two objects between each other. In your use case however since there is only one Field which differs, I would be tempted to just add a method to the struct.

[@frontend6556]

What is the font name in vscode? 6:55

[@GeekInLinux]

thanks for the video, i have a problem. swagger init works but swagger generate overrides it and make it empty

[@sovrinfo]

Thank you very much!!!

[@ganeshyadav6217]

hello nic,,,whenever i try to run command "make swagger" , I encounter with make : The term 'make' is not recognized as the name of a cmdlet, function, script file, or operable program. Check the spelling of the name, or if a path was included, verify that the path is correct and try again.

[@vijaykarajgikar697]

When I run the swagger generate, I get an error "-bash: swagger: command not found". Need to know how to get this fixed. Do I have to install swagger?

[@mehranjanfeshan]

It seems that the code is heavily refactored compares to what explained in episode 6. Am I missing something here?

[@r080d]

Thank you, NIC!!

[@daisytran4813]

paths: {} swagger: "2.0" After following every guide below such as leaving no space between the documentation and the package definition, I still encounter this! Has anyone figured this out 2024 :( ?

[@MsAidahar]

Why you don't use code from last video?

[@pornpimonwp6]

thank you very much :)

[@AsaduzzamanSohel]

I cant set up swagger on ubuntu 20.04. When I did make swagger cmd on my terminal, it creat swagger.json like this ```info: {} paths: {} swagger: "2.0" ``` How can I fix this?

[@aidarark5558]

can someone tell why are we setting GO111MODULE=off in the Makefile? And what if i remove this command?

[@lcslima45]

When I run mingw32-make swagger the swagger.yaml i get is void info: {} paths: {} swagger: "2.0" What do I do?

[@antonyndungu3075]

Just wondering if Redoc documentation can be interactive like Swagger UI

[@NicJackson]

It does look like the Redoc can handle requests, but I is not as comprehensive as the Swagger API. The usual pattern for Swagger UI is that it is generally installed at a single location rather than being distributed with each service.

[@antonyndungu3075]

I agree Swagger UI is more comprehensive, I downloaded Swagger UI, copied the contents of the dist folder into a folder in my project and outputted swagger.json into the same folder and changed the url in index.html to ./swagger.json and served the folder static files with go at /docs route. So that if someone goes to that path they’re serve with Swagger UI with my json file. The result is an interactive docs for the API.

[@geobonsai3590]

I am having trouble with swagger. When I type make swagger I am getting " /usr/bin/sh: swagger: command not found " . I working on windows 10 with git bash and VS code. I have followed the instructions about the installation and tried to find more info on the internet but nothing found. Any ideas? please!!

[@brandonmandzik8858]

Install Swagger on your local machine first

[@sprasoon]

I am using windows 10. Installed swagger using "go get -u github.com/go-swagger/go-swagger/cmd/swagger ". unable to generate swagger document from swagger generate spec -o ./swagger.yaml --scan-models. Terminal returns with error swagger is not recognized as an internal or external command. Please advice. Thanks

[@vishalhasija5910]

When you install swagger, swagger.exe will be generated in your gopath/bin folder. Set the gopath/bin (complete bin path) in your Environment Variable PATH or alternatively place swagger.exe in C:\Windows\System32. This should solve your issue.

[@yzzyyzzyyzzy]

I run your Makefile but get error: ' classifier: unknown swagger annotation "mete" '. I am sorry i am in china.

[@harishreddy8439]

'GO111MODULE' is not recognized as an internal or external command, operable program or batch file. Could you help me with this error?

[@NicJackson]

GO111MODULE is the environment variable for controlling if the new modules are used. What command are you trying to run Harish?

[@harishreddy8439]

@@NicJackson 'make swagger' Since GO111MODULE is present in the Makefile I'm receiving that error.

[@devotedindian545]

This has been my most horrifying predicament, in my terminal of vscode, the curl doesn't work like yours, my make is not working, even swagger generates no spec, i can't even get it to work since 2 days. Its so frustrating. this is by fa the best series i have stuck to, but please give instructions of your setup if u have made any special settings, its a nightmare on windows

[@NicJackson]

Lets run through this step by step :) Firstly curl, which OS are you using and which version of curl do you have installed. If you are using Windows are you using it through WSL or WSL2 or just native in the command promtpt?

[@devotedindian545]

@@NicJackson primarily thank you a tonne for replying, i use the default terminal which is the powershell, it gave me errors for curl, so i installed "curl-7.70.0-win64-mingw" for windows, it worked then, from 7th episode you started using make, so i decided i'll make use of WSL, but then it couldn't recognise my go command, so i parted with it not wanting to waste time, i directly installed swagger, added it path to my path variable, and use the command directly , it still wasn't generating spec for my handler, so i copied your code from the repository, and tried to run it till won't generate, then a few minutes ago i notice i had space between package declaration and swagger:meta, after changing that it worked, i have been stuck on this episode since yesterday and the reason was a blank line :D, have you installed go in your subsystem only ? and use just that ?, my go is installed on my windows and so interoperability issues creep up. But all this is my shortcomings , your series has been thoroughly rewarding.

[@NicJackson]

Primarily I use Go in WSL2 I do have Go installed on native Windows to check things from time to time but when developing I use WSL2. There are subtle differences to the way things work on Linux / Mac and Windows, so I tend to stick to Linux. In my humble opinion it is worth using WSL2 and getting set up with it, I believe Microsoft are committed to running with that moving forward. VSCode integration is great between the Windows Desktop WSL2 and Windows hosted VSCode. You can also run the Linux version of Docker in WSL2 So for generating the Swagger, you need to install the Swagger CLI, this can be done with the following command: go get -u github.com/go-swagger/go-swagger/cmd/swagger Then you can generate the Swagger documentation: swagger generate spec -o ./swagger.yaml --scan-models Once you have that run the server , windows will prompt you to add a firewall exception, click ok: go run main.go To get the documentation you should be able to do: curl localhost:9090/swagger.yaml Or open the following link in your browser: localhost:9090/docs Lots of folks use Windows it seems so I will make sure that I use Windows compatible instructions or provide options for both OS moving forward.

[@devotedindian545]

@@NicJackson Again thank you a tonne maan, i love your teaching style and it has just been the best series i have taken up since a long time. ill follow your instructions and set it up. i owe you dude 🙏🙏🙏

[@jonleopard4315]

Hey Nic! Do you know of any go packages that handle Open API v3.0? I'm using Chi (router), and would like to start documenting my API's with swagger, but ideally using the latest spec. I found this package but perhaps you know of a better one? github.com/deepmap/oapi-codegen Thanks for making quality videos!

[@manofqwerty]

I am getting a 404 for the swagger.yaml file, anyone have any ideas why this may be?

[@manofqwerty]

Hey, so I figured this out. For anyone else who has a similar issue, my issue was that Swagger did not like being on a subrouter. I was using `r := router.PathPrefix("/api").Subrouter()` to generate a sub router and then trying to handle swagger on r. Once I changed to using the base router, the issue went away. Hope this helps someone.

[@dimayasnohurskyi2805]

Hi, you did refactoring code offline? Because starting from this video become harder to follow you...

[@dimayasnohurskyi2805]

I've cloned code from this episode (7) and this request that worked from previous episode not works now: curl -v localhost:9090/products -XPOST -d '{"NAME":"new", "price":12.2, "SKU":"asd-asd-fds"}' Error: http: panic serving [::1]:43916: interface conversion: error is nil, not validator.ValidationErrors

[@KoreanMacho]

I see that he did refactor code offline.

[@dimayasnohurskyi2805]

@Şəhriyar Rzayev just relax, this lessons is not best practices, only starting point.

[@TheBeast2109]

@@dimayasnohurskyi2805 yes my curl commands also e.g. POST PUT are not working. Did you get a fix?

[@eddykeen23]

​@@TheBeast2109 anyone find a fix for the POST and PUT? I'm going to look into this.

[@siddhantsharma5125]

i am getting the following error: which swagger || GO111MODULE=off go get -u github.com/go-swagger/go-swagger/cmd/swagger 'which' is not recognized as an internal or external command, operable program or batch file. 'GO111MODULE' is not recognized as an internal or external command, operable program or batch file. make: *** [check_install] Error 1 can someone please help?

[@NicJackson]

Hi Siddhant are you using Windows?

[@siddhantsharma5125]

@@NicJackson yessir

[@NicJackson]

So I apologise but I wrote the Makefile for Unix and which is a command to return the location of another command. In this instance I am checking to see if you have the swagger CLI tool installed before running the command. Try this.. Install Swagger CLI: go get -u github.com/go-swagger/go-swagger/cmd/swagger Generate Swagger Docs: swagger generate spec -o ./swagger.yaml --scan-models

[@siddhantsharma5125]

@@NicJackson thank you!

[@jayeshthamke7860]

Hi Nic, the api documentation can be viewed/accessed (via /doc endpoint) until the server is running (github.com/nicholasjackson/building-microservices-youtube/blob/episode_7/product-api/main.go#L54). How can I host the api spec to a static website/page which is available irrespective of server running status? Thanks

[@agustincontrerasmoiraghira1852]

I didn't try it yet, but you could start a swagger ui docker container swagger.io/docs/open-source-tools/swagger-ui/usage/installation/

[@jayeshthamke7860]

gh pages may be helpful to host apidoc

[@titusdishon5109]

Error running 'swagger' CreateProcess error=2, The system cannot find the file specified anyone getting this error on windows? please help

[@NicJackson]

Hi there, I use Windows myself but generally with WSL2 and Linux. I have however just installed Go on Windows to check this. First thing I noticed is that the Makefile is not compatible with Windows. I will fix that in a bit but for now can you run the following commands successfully... This command will install the go-swagger CLI which is used for generating the docs: go get -u github.com/go-swagger/go-swagger/cmd/swagger This command will actually generate the documentation: swagger generate spec -o ./swagger.yaml --scan-models You need to run this command from the product-api folder not the root repo folder. F:\code\go\src\github.com icholasjackson\building-microservices-youtube\product-api>dir Volume in drive F is Scratch Volume Serial Number is 0637-03F1 Directory of F:\code\go\src\github.com icholasjackson\building-microservices-youtube\product-api 05/07/2020 08:56 PM . 05/07/2020 08:56 PM .. 05/07/2020 08:56 PM data 05/07/2020 08:56 PM 411 go.mod 05/07/2020 08:56 PM 14,721 go.sum 05/07/2020 08:56 PM handlers 05/07/2020 08:56 PM 2,639 main.go 05/07/2020 08:56 PM 202 Makefile 05/07/2020 08:56 PM 4,801 swagger.yaml 5 File(s) 22,774 bytes 4 Dir(s) 193,160,728,576 bytes free F:\code\go\src\github.com icholasjackson\building-microservices-youtube\product-api>swagger generate spec -o ./swagger.yaml When I run that it works great for me but I apologies for your troubles

[@titusdishon5109]

Hi nick, first thank you for the great tutorials. I you have really taught me a lot. I was almost hating golang. I will do that and get back to you. thanks

[@NicJackson]

Go like all languages requires a little paitents in the beginning. But sometimes the error is just plain confusing. Go works pretty well on Windows natively, but differences in the OS simple things like they way environment variables are loaded can be a real problem when scripts are targeted for Linux. I am guilty of this myself, I'm going to make sure that any commands I issue are also functional for folks running Windows Go natively.

[@NicJackson]

I will add to this, the Windows ecosystem is a good development environment but it shines with WSL and Ubuntu. I'm going to create a video on this

[@titusdishon5109]

@@NicJackson I have been following the way you use the docs and I think this is going to held me a lot. I have been using python and did not feel the power in it. Atleast with your fluent tutorial am getting the best of Golang , once more thank you very much

[@RAVIKUMAR-nx3od]

I really like your tutorials but some of the stuff you skip without describing in the videos like in REST , you directly added DELETE method without mentioning in the REST episode . Also, I always see some changes here and there with new videos. I am a beginner with Golang, it makes me sad when I can't figure out things properly.

[@NicJackson]

Hey Ravi, there were definitely some learning curves for me when creating these videos, I apologize for the early refactoring. When I was creating the content I tried to do things as live as possible, my intention was to show my thought process as I was building up the content. One thing I did not account for was that generally when writing code I create an initial draft that allows me to get a rough shape and then I refactor it to clean things up. I mostly did not show the refactoring and this caused some continuity between episodes. Apologies for this, definitely a lesson learned.

[@RAVIKUMAR-nx3od]

@@NicJackson Thank you for the information

[@magomedadizov3312]

looks like this is my last video. Nothing works im done (

[@Jeremiahhard]

swagger is not working. I'm using mac and Goland

[@Jeremiahhard]

@nic Jackson. Thanks for this great series. I'm on mac using Golang. Swagger not working at all after using your method. Can you help us using Mac.

[@rajopinion2958]

hii unable to swagger in windows it is giving error in swagger not recognizwd as internal or external command,but i have insalled swagger ,guide me please