[[:oktatas:web:back-end_framework:express:swagger|< Swagger]]
====== Express - Swagger JsDoc ======
* **Szerző:** Sallai András
* Copyright (c) 2023, Sallai András
* Szerkesztve: 2024
* Licenc: [[https://creativecommons.org/licenses/by-sa/4.0/|CC Attribution-Share Alike 4.0 International]]
* Web: https://szit.hu
===== Projekt =====
mkdri app01
cd app01
npm init -y
Függőségek:
pnpm install --save express nodemon morgan
pnpm install --save-dev swagger-jsdoc swagger-ui-express
Script:
{
"scripts": {
"start":"nodemon app --watch app"
}
}
===== Szerver =====
const express = require('express')
const app = new express()
const morgan = require('morgan')
const router = require('./routes/api')
const PORT = process.env.PORT || 8000;
app.use(express.json())
app.use(morgan('tiny'))
app.use(router)
app.listen(PORT, () => {
console.log('Server is running on port: ', PORT)
})
===== Az index.js kiegészítése =====
const express = require('express')
const app = new express()
const morgan = require('morgan')
const router = require('./routes/api')
const swaggerUi = require('swagger-ui-express')
const swaggerOptions = {
swaggerDefinition: {
info: {
title: 'Teszt API',
version: '0.0.1'
}
},
apis: ['app/routes/api.js']
}
const swaggerJsDoc = require('swagger-jsdoc');
const swaggerDocument = swaggerJsDoc(swaggerOptions)
const PORT = process.env.PORT || 8000;
app.use('/swagger', swaggerUi.serve)
app.get('/swagger', swaggerUi.setup(swaggerDocument))
app.use(express.json())
app.use(morgan('tiny'))
app.use(router)
app.listen(PORT, () => {
console.log('Server is running on port: ', PORT)
})
===== Routing =====
const router = require('express').Router();
const EmployeeController = require('../controllers/employeecontroller');
/**
* @swagger
* /ping:
* get:
* description: Elérhetőség viszgálata
* responses:
* 200:
* description: Success
*
*/
router.get('/ping', async (req, res) => {
res.send({message: 'Helló'})
})
module.exports = router
Nézzük meg az eredményt:
* http://localhost:8000/api-docs/
===== Post kérés =====
Hozzunk létre egy /emp útvonalat POST metódussal.
const router = require('express').Router();
const swaggerUi = require('swagger-ui-express')
const swaggerJsDoc = require('swagger-jsdoc');
const swaggerOptions = {
swaggerDefinition: {
info: {
title: 'Teszt API',
version: '0.0.1'
}
},
apis: ['app/routes/api.js']
}
const swaggerDocument = swaggerJsDoc(swaggerOptions)
console.log(swaggerDocument)
router.use('/api-docs', swaggerUi.serve)
router.get('/api-docs', swaggerUi.setup(swaggerDocument))
/**
* @swagger
* /ping:
* get:
* description: Elérhetőség viszgálata
* responses:
* 200:
* description: Success
*
*/
router.get('/ping', async (req, res) => {
res.send({message: 'Helló'})
})
/**
* @swagger
* /emp:
* post:
* description: Create employee
* parameters:
* - name: name
* description: the employee's name
* in: formData
* required: true
* type: string
* responses:
* 201:
* description: Created
*
*/
router.post('/emp', async (req, res) => {
res.status(201).send()
})
module.exports = router
Nézzük meg az eredményt:
* http://localhost:8000/api-docs/