El Projecte | Sobre nosaltres | Contribuir | Donacions | Llicència
HOME Els meus cursos Finalitzats
◄ Anterior
◄

Swagger per a documentació

Següent ►
►

Swagger és una eina poderosa i àmpliament utilitzada per a la documentació d'APIs RESTful. Proporciona una interfície interactiva que permet als desenvolupadors explorar i provar les seves APIs de manera fàcil i eficient. En aquesta secció, aprendrem què és Swagger, com utilitzar-lo per documentar una API i com integrar-lo en el nostre projecte.

Què és Swagger?

Swagger és un conjunt d'eines de codi obert per a la creació, definició i documentació d'APIs RESTful. La seva característica més destacada és Swagger UI, una interfície d'usuari que permet als desenvolupadors interactuar amb l'API directament des del navegador.

Característiques principals de Swagger:

  • Documentació interactiva: Permet als usuaris provar les peticions directament des de la documentació.
  • Generació automàtica de documentació: A partir de les anotacions en el codi, Swagger pot generar la documentació de manera automàtica.
  • Suport per a múltiples llenguatges: Swagger és compatible amb diversos llenguatges de programació i frameworks.

Instal·lació de Swagger

Per començar a utilitzar Swagger en el nostre projecte, primer hem d'instal·lar les dependències necessàries. A continuació, es mostra com fer-ho en un projecte Node.js utilitzant Express.

Instal·lació de dependències

npm install swagger-ui-express swagger-jsdoc

Configuració de Swagger en un projecte Express

  1. Crear un fitxer de configuració per a Swagger: Aquest fitxer contindrà la informació bàsica de la nostra API.
// swaggerConfig.js
const swaggerJsDoc = require('swagger-jsdoc');

const swaggerOptions = {
  swaggerDefinition: {
    openapi: '3.0.0',
    info: {
      title: 'API de Exemple',
      version: '1.0.0',
      description: 'Documentació de la nostra API de Exemple',
    },
    servers: [
      {
        url: 'http://localhost:3000',
      },
    ],
  },
  apis: ['./routes/*.js'], // Ruta als fitxers on es troben les nostres rutes
};

const swaggerDocs = swaggerJsDoc(swaggerOptions);
module.exports = swaggerDocs;
  1. Integrar Swagger en el servidor Express:
// server.js
const express = require('express');
const swaggerUi = require('swagger-ui-express');
const swaggerDocs = require('./swaggerConfig');

const app = express();
const port = 3000;

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocs));

app.listen(port, () => {
  console.log(`Servidor en funcionament a http://localhost:${port}`);
});
  1. Anotar les rutes amb Swagger: Utilitzarem comentaris especials per descriure les nostres rutes.
// routes/example.js
/**
 * @swagger
 * /example:
 *   get:
 *     summary: Obtenir un exemple
 *     responses:
 *       200:
 *         description: Èxit
 */
app.get('/example', (req, res) => {
  res.status(200).send('Exemple');
});

Exploració de la documentació

Un cop configurat Swagger, podem accedir a la documentació interactiva de la nostra API navegant a http://localhost:3000/api-docs. Aquí podrem veure totes les rutes documentades, els paràmetres que accepten, les respostes que retornen i provar les peticions directament des del navegador.

Exercici pràctic

Objectiu

Documentar una API senzilla amb Swagger.

Passos

  1. Crear una API bàsica amb Express:

    • Crea un projecte Node.js.
    • Instal·la Express i Swagger.
    • Configura un servidor bàsic amb una ruta /example.

  2. Documentar la ruta /example amb Swagger:

    • Afegeix comentaris Swagger a la ruta.
    • Configura Swagger per generar la documentació.

Solució

// server.js
const express = require('express');
const swaggerUi = require('swagger-ui-express');
const swaggerJsDoc = require('swagger-jsdoc');

const app = express();
const port = 3000;

const swaggerOptions = {
  swaggerDefinition: {
    openapi: '3.0.0',
    info: {
      title: 'API de Exemple',
      version: '1.0.0',
      description: 'Documentació de la nostra API de Exemple',
    },
    servers: [
      {
        url: 'http://localhost:3000',
      },
    ],
  },
  apis: ['./routes/*.js'],
};

const swaggerDocs = swaggerJsDoc(swaggerOptions);
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocs));

app.get('/example', (req, res) => {
  res.status(200).send('Exemple');
});

app.listen(port, () => {
  console.log(`Servidor en funcionament a http://localhost:${port}`);
});
// routes/example.js
/**
 * @swagger
 * /example:
 *   get:
 *     summary: Obtenir un exemple
 *     responses:
 *       200:
 *         description: Èxit
 */
app.get('/example', (req, res) => {
  res.status(200).send('Exemple');
});

Resum

En aquesta secció, hem après què és Swagger i com utilitzar-lo per documentar una API RESTful. Hem vist com instal·lar les dependències necessàries, configurar Swagger en un projecte Express i anotar les rutes per generar la documentació automàticament. Swagger és una eina essencial per a qualsevol desenvolupador d'APIs, ja que facilita la creació de documentació clara i interactiva, millorant la col·laboració i la comprensió de l'API per part de tots els implicats.

◄ Anterior
◄
Següent ►
►
El Projecte | Sobre nosaltres | Contribuir | Donacions | Llicència
© Copyright 2024. Tots els drets reservats