An Interest In:
Web News this Week
- April 22, 2024
- April 21, 2024
- April 20, 2024
- April 19, 2024
- April 18, 2024
- April 17, 2024
- April 16, 2024
Documenting your ExpressWebJs API with Swagger
Almost every application today has to be connected to share data with other applications. The best way to do that is through APIs and ExpressWebjs is the goto framework for building your node apis.
In this tutorial, however, were going to explore Swagger usage along with expressWebjs.
What is Swagger?
On the Swagger site we can find definition of Swagger:
Swagger is the worlds largest framework of API developer tools for the OpenAPI Specification(OAS), enabling development across the entire API lifecycle, from design and documentation, to test and deployment.
In our example, well be making use of the two libraries: swagger-ui-express and swagger-jsdoc.
The first is a module that allows you to feed a Swagger UI (auto-generated views based on the swagger-ui project) from a swagger.json file, or from an inline object.
The second is about integrating Swagger using JSDoc comments in Docs directory in ExpressWebjs. This is pretty useful, especially when you have extensive APIs and dozens of models.
Application setup
Install ExpressWebJs
Run the following command in your terminal to create a new project with ExpressWebJs:
npx expresswebcli new myNewApp
cd into your newly created project.
cd myNewApp
Visit my article on developing rest apis with expresswebjs or expresswebjs documentation for work through on how to get started with expresswebjs.
Adding swagger
Now that our application is ready,
we can now integrate swagger by creating our swagger.json file in the root directory
{ "definition": { "openapi": "3.0.n", "info": { "title": "My Website API Documentation", "version": "0.1.0", "description": "My website API docs with ExpressWebJs and documented with Swagger", "license": { "name": "MIT", "url": "https://spdx.org/licenses/MIT.html" }, "contact": { "name": "" } }, "servers": [ { "url": "http://localhost:5100/api" } ] }, "apis": ["./Docs/*.js"] }
This "apis": ["./Docs/*.js"]
section specifies the path where your actual documentations are. In our case, it is in Docs folder in the root directory.
After that we can now create our swagger service in App/Service directory.
In App/Service directory, lets create a Swagger folder with an index.js file. Our path will be App/Service/Swagger/index.js
//App/Service/Swagger/index.jsconst swaggerJsdoc = require("swagger-jsdoc");const swaggerUi = require("swagger-ui-express");const options = require("../../../swagger.json");class Swagger{ static run(){ let specs = swaggerJsdoc(options); serverApp.use("/api-docs",swaggerUi.serve,swaggerUi.setup(specs,{exporer:true})); }}module.exports = Swagger;
ExpressWebJs ServiceProvider
Next we will register our swagger service in our application service provider. Navigate to App/Providers/AppServiceProvider.js file and add our swagger service to be executed at boot time
const swagger = require("../Service/swagger"); class AppServiceProvider { /** * Register application services. */ register() { return { // }; } /** * Bootstrap any application services. * * @return void */ boot() { swagger.run(); }}module.exports = AppServiceProvider;
Note: you can create your own service provider. Read more about ExpressWebjs ServiceProvider in the Documentation site.
Once all the setup is done, you can now start writing your api documentation in the Docs directory.
To view your swagger docs, run your project using
npm run dev
and navigate to http://127.0.0.1/api/api-docs
in your browser.
Conclusion
Thank you for reading my article
You can follow me on twitter @EmekaIgbokwe
You can follow ExpressWebJs on twitter @expresswebjs
and don't forget to star on github ExpressWebJs
Please, let me know if you have any questions in the comment section.
Original Link: https://dev.to/alexigbokwe/documenting-your-expresswebjs-api-with-swagger-36hf
Dev To
An online community for sharing and discovering great ideas, having debates, and making friendsMore About this Source Visit Dev To