This week, I got a task to write swagger document, at the beginning, I thought it wasn’t hard. But…. after I got stuck for a few days, now i got my first swagger working in azure.
My swagger not perfect, but good enough !
I am using NodeJS as environment, main package is swagger.
Notice that: this package follows openAPI -specification version 2.0. The latest openAPI version is 3.0. If you need latest version, try to search for another package.
Then I tried to follow official instruction
- swagger project create projectname
- choose framework
- swagger project start projectname
Then, I got those,
Especially, in my project folder, swagger created another “todolist” project. crying….. This is not what i want. I have my api, routes, serverJS, in my case, I just want one yaml document to show swagger.
Thus, I use different command,
- I created a swagger.yaml file in my swagger folder under api folder , as the swagger’s default path is “api/ swagger/swagger.yaml”.
- installing some packages:
(add –save , to record it into package.json) - add some basic data into this swagger.yaml , for example
4. then, in your CLI, YOU can run “swagger project edit” (Mention that without add those data pic above, you cannot use this command.)
Now you can see your swagger editor
The last step, read openAPI 2.0 document to learn how to write in formal way. And ignore those error at the beginning, when you finish one method, then check error. If you did not finish one method, it always show some error. Anddddd, do not forget to refresh page sometimes for clean error.
After your swagger.yaml is done, how to host it ?
- npm install swagger-ui-express –save
- add those code to your app.js or server.js or index.js
3. now test it, swagger project start
4. in browser, input “localhost:3000/help” (because in picture above, i set path is “/help”).
Even, I pushed it into Azure cloud, Azure will deploy it automatically. But do not forget to change “host” in yaml file.
learning Swagger 2.0 specification is comming….
RITA: A STRUGGLING PROGAMMMER 