szit

Ez az oldal csak olvasható. Megtekintheted a forrását, de nem változtathatod meg. Ha úgy gondolod, hogy ez helytelen, kérdezd az Adminisztrátorokat!
[[:oktatas:web:back-end_framework:express:swagger|< Swagger]]

====== Express - Swagger automatikus generálása ======

  * **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>

===== A Swagger beépítése =====

Az index.js fájlban:

<code javascript>
//...
const swaggerUi = require('swagger-ui-express')
const swaggerDocument = require('../swagger-output.json')

app.use('/swagger', swaggerUi.serve, swaggerUi.setup(swaggerDocument))
//...

</code>

Az utolsó sor szétbontható két részre. A teljes fájlban így fog szerepelni.


A teljes fájl:
<code javascript 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 swaggerDocument = require('../swagger-output.json')

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('/api', router)

app.listen(PORT, () => {
    console.log('Server is running on port: ', PORT)
})

</code>


A Swagger most egy JSON fájlból dolgozik aminek a neve most: swagger-output.json.
A fájl viszont most automatikusan generálódik.

===== Routing =====

<code javascript routes/api.js>
const router = require('express').Router();

const EmployeeController = require('../controllers/employeecontroller');

router.get('/employees', EmployeeController.index)
router.post('/employees', EmployeeController.store)

module.exports = router
</code>

===== Automatikus Swagger generálás =====

Szükségünk van egy újabb csomagra:

  npm install --save-dev swagger-autogen


Készítsünk a projekt gyökérkönyvtárában egy swagger.js fájlt, a következő tartalommal:

<code javascript swagger.js>
const swaggerAutogen = require('swagger-autogen')({openapi: '3.0.0'});

const doc = {
  info: {
    title: 'Dolgozók REST API',
    description: 'Teszt'
  },
  servers: [
    {
        url: 'http://localhost:8000/api',
        description: ''
    }
  ]
};

const outputFile = './swagger-output.json';
const routes = ['./app/routes/api.js'];

swaggerAutogen(outputFile, routes, doc);
</code>

Írjunk egy scriptet a package.json fájlban:

<code javascript package.json>
  "scripts": {
    "start": "node app",
    "dev": "nodemon app --watch app",
    "doc": "node ./swagger.js"
  },
</code>

A futtatás:
  npm run doc


A kontrollerben szerepelnie kell önmagában vagy szelekcióban a kötelező mezőknek.

<code javascript>
        req.body.name
        req.body.city
        req.body.salary
        req.body.positionId
</code>

Teljes kód:


<code javascript app/controllers/employeecontroller.js>
    async store(req, res) {
        
        req.body.name
        req.body.city
        req.body.salary
        req.body.positionId

        try {
            await EmployeeController.tryStore(req, res)
        } catch (error) {
            if (error instanceof Sequelize.ValidationError) {
                res.status(400)
            }else {
                res.status(500)
            }
            const errorMessage = error.errors[0].message
            res.json({
                success: true,
                message: 'Error! The update is failed!',
                error: errorMessage
            })
        }        
    },
    async tryStore(req, res) {
        const emp = await Employee.create(req.body)
        res.status(201)
        res.json({
            success: true,
            data: emp
        })
    },
</code>


==== A store függvényben ellenőrzéssel ====

<code javascript app/controllers/employeecontroller.js>
//...
    async store(req, res) {
        if(!req.body.name ||
            !req.body.city ||
            !req.body.salary ||
            !req.body.positionId) {
            res.status(400)
            res.json({
                success: false,
                message: 'Hiba! A bejövő adatok hibásak!'
            })
        }

        try {
            await EmployeeController.tryStore(req, res)
        } catch (error) {
            if (error instanceof Sequelize.ValidationError) {
                res.status(400)
            }else {
                res.status(500)
            }
            const errorMessage = error.errors[0].message
            res.json({
                success: true,
                message: 'Error! The update is failed!',
                error: errorMessage
            })
        }        
    },
    async tryStore(req, res) {
        const emp = await Employee.create(req.body)
        res.status(201)
        res.json({
            success: true,
            data: emp
        })
    },
//...
</code>

===== Body paraméterek haladó módon =====

Swagger annotációt fogunk használni a body paraméterek értelmezésére.

<code javascript app/controllers/employeecontroller.js>
//...

    async store(req, res) {
    /*
        #swagger.parameters['body'] = {
            in: 'body',
            description: 'Dolgozó adatai',
            required: true,
            schema: {
                name: "Valaki",
                city: "Valahol",
                salary: 300.0,
                positionId: 1
            }
        }
    */

        try {
            const emp = await Employee.create(req.body)
            res.status(201)
            res.json({
                success: true,
                data: emp
            })
        } catch (error) {
            res.status(500)
            res.send('Hiba')
        }
    },

//...
</code>

Közvetlen dokumentáció: 
  * https://swagger-autogen.github.io/docs/endpoints/manual-capture (2024)
==== Linkek ====

  * https://swagger-autogen.github.io/docs/ (2024)