[[: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:

<code>
pnpm install --save express nodemon morgan
pnpm install --save-dev swagger-jsdoc swagger-ui-express
</code>


Script:

<code javascript package.json>
{
  "scripts": {
    "start":"nodemon app --watch app"
  }
}
</code>

===== Szerver =====

<code javascript app/index.js>
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)
})
</code>

===== Az index.js kiegészítése =====

<code javascript app/index.js>
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)
})

</code>




===== Routing =====

<code javascript app/routes/api.js>
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

</code>


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.


<code javascript app/routes/api.js>
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
</code>


Nézzük meg az eredményt:
  * http://localhost:8000/api-docs/