Swagger-Praxis-Tutorial: Buchverwaltungs-API

Dieses Tutorial führt Sie durch die Implementierung einer Swagger-basierten API für ein Buchverwaltungssystem. Die Hauptfunktionen umfassen:

  • CRUD-Operationen für Bücher
  • Paginierte Abfragen
  • Bedingungsbasierte Filterung
  • Automatische Generierung der API-Dokumentation
  • Online-API-Tests

Tech-Stack:

  • Node.js + Express
  • Swagger UI Express
  • Swagger JSDoc

Umgebungsvorbereitung

Node.js installieren

Stellen Sie sicher, dass Node.js auf Ihrem System installiert ist (v14.0.0 oder höher empfohlen).

Umgebung prüfen

node -v
npm -v

Projektinitialisierung

Projektverzeichnis erstellen

mkdir book-management-api
cd book-management-api
npm init -y

Abhängigkeiten installieren

npm install express cors swagger-ui-express swagger-jsdoc nodemon --save

Grundlegende Projektstruktur erstellen

book-management-api/
├── node_modules/
├── models/
│   └── book.js
├── routes/
│   └── books.js
├── middleware/
│   └── auth.js
├── swagger/
│   └── swagger.js
├── app.js
└── package.json

Einstiegsdatei app.js erstellen

Beispiel

const express = require('express');
const cors = require('cors');
const swaggerUi = require('swagger-ui-express');
const swaggerSpec = require('./swagger/swagger');
const booksRouter = require('./routes/books');

const app = express();
const PORT = process.env.PORT || 3000;

// Middleware
app.use(cors());
app.use(express.json());
app.use(express.urlencoded({ extended: true }));

// API-Routen
app.use('/api/books', booksRouter);

// Swagger-Dokumentation
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));

// Server starten
app.listen(PORT, () => {
  console.log(`Dienst gestartet, Zugriff auf http://localhost:${PORT}`);
  console.log(`Adresse der API-Dokumentation: http://localhost:${PORT}/api-docs`);
});

API-Design und Implementierung

Buchmodell erstellen

Inmodels/book.jsEin einfaches In-Memory-Datenmodell erstellen:

Beispiel

// models/book.js
let books = [
  { id: 1, title: 'Tiefes Verständnis von JavaScript', author: 'Douglas Crockford', publishDate: '2008-01-01', isbn: '978-0596517748', category: 'Programmierung' },
  { id: 2, title: 'Node.js in Aktion', author: 'Alex Young', publishDate: '2014-08-01', isbn: '978-1617290572', category: 'Programmierung' },
  { id: 3, title: 'Die drei Sonnen', author: 'Liu Cixin', publishDate: '2008-01-01', isbn: '978-7536692387', category: 'Science-Fiction' }
];

let nextId = 4;

module.exports = {
  // Alle Bücher abrufen
  getAll: (page = 1, limit = 10, filter = {}) => {
    let result = [...books];
   
    // Filterbedingungen anwenden
    if (filter.category) {
      result = result.filter(book => book.category === filter.category);
    }
   
    if (filter.author) {
      result = result.filter(book => book.author.includes(filter.author));
    }
   
    if (filter.title) {
      result = result.filter(book => book.title.includes(filter.title));
    }
   
    // Paginierung berechnen
    const startIndex = (page - 1) * limit;
    const endIndex = page * limit;
   
    return {
      total: result.length,
      page: page,
      limit: limit,
      data: result.slice(startIndex, endIndex)
    };
  },
 
  // Ein einzelnes Buch abrufen
  getById: (id) => {
    return books.find(book => book.id === id);
  },
 
  // Buch erstellen
  create: (book) => {
    const newBook = { ...book, id: nextId++ };
    books.push(newBook);
    return newBook;
  },
 
  // Buch aktualisieren
  update: (id, bookData) => {
    const index = books.findIndex(book => book.id === id);
    if (index !== -1) {
      books[index] = { ...books[index], ...bookData };
      return books[index];
    }
    return null;
  },
 
  // Buch löschen
  delete: (id) => {
    const index = books.findIndex(book => book.id === id);
    if (index !== -1) {
      const deletedBook = books[index];
      books.splice(index, 1);
      return deletedBook;
    }
    return null;
  }
};

Route-Controller implementieren

Inroutes/books.jsAPI-Routen implementieren:

Beispiel

// routes/books.js
const express = require('express');
const router = express.Router();
const Book = require('../models/book');

/**
 * @swagger
 * components:
 * schemas:
 * Book:
 * type: object
 * required:
 * - title
 * - author
 * - isbn
 * properties:
 * id:
 * type: integer
* description: Buch-ID
 * title:
 * type: string
* description: Buchtitel
 * author:
 * type: string
* description: Autor
 * publishDate:
 * type: string
 * format: date
* description: Veröffentlichungsdatum
 * isbn:
 * type: string
* description: ISBN-Nummer
 * category:
 * type: string
* description: Buchkategorie
 */


/**
 * @swagger
 * /api/books:
 * get:
* summary: Bücherliste abrufen
* description: Gibt alle Bücher zurück, unterstützt Paginierung und Filterung
 * parameters:
 * - in: query
 * name: page
 * schema:
 * type: integer
 * default: 1
* description: Seitennummer
 * - in: query
 * name: limit
 * schema:
 * type: integer
 * default: 10
* description: Anzahl pro Seite
 * - in: query
 * name: category
 * schema:
 * type: string
* description: Nach Kategorie filtern
 * - in: query
 * name: author
 * schema:
 * type: string
* description: Nach Autor filtern
 * - in: query
 * name: title
 * schema:
 * type: string
* description: Nach Titel filtern
 * responses:
 *       200:
* description: Bücherliste erfolgreich abgerufen
 * content:
 * application/json:
 * schema:
 * type: object
 * properties:
 * total:
 * type: integer
 * page:
 * type: integer
 * limit:
 * type: integer
 * data:
 * type: array
 * items:
 * $ref: '#/components/schemas/Book'
 */

router.get('/', (req, res) => {
  const page = parseInt(req.query.page) || 1;
  const limit = parseInt(req.query.limit) || 10;
  const filter = {};
 
  if (req.query.category) filter.category = req.query.category;
  if (req.query.author) filter.author = req.query.author;
  if (req.query.title) filter.title = req.query.title;
 
  const result = Book.getAll(page, limit, filter);
  res.json(result);
});

/**
 * @swagger
 * /api/books/{id}:
 * get:
* summary: Ein einzelnes Buch abrufen
* description: Detaillierte Informationen zu einem bestimmten Buch anhand der ID abrufen
 * parameters:
 *       - in: path
 * name: id
 * required: true
 * schema:
 * type: integer
* description: Buch-ID
 * responses:
 *       200:
* description: Buch erfolgreich abgerufen
 * content:
 * application/json:
 * schema:
 * $ref: '#/components/schemas/Book'
 *       404:
* description: Buch nicht gefunden
 */

router.get('/:id', (req, res) => {
  const id = parseInt(req.params.id);
  const book = Book.getById(id);
 
  if (book) {
    res.json(book);
  } else {
    res.status(404).json({ message: 'Book not found' });
  }
});

/**
 * @swagger
 * /api/books:
 * post:
* summary: Ein neues Buch erstellen
* description: Ein neues Buch zum System hinzufügen
 * requestBody:
 * required: true
 * content:
 * application/json:
 * schema:
 * type: object
 * required:
 * - title
 * - author
 * - isbn
 * properties:
 * title:
 * type: string
 * author:
 * type: string
 * publishDate:
 * type: string
 * format: date
 * isbn:
 * type: string
 * category:
 * type: string
 * responses:
 *       201:
* description: Buch erfolgreich erstellt
 * content:
 * application/json:
 * schema:
 * $ref: '#/components/schemas/Book'
 *       400:
* description: Ungültige Eingabedaten
 */

router.post('/', (req, res) => {
  // Einfache Validierung
  if (!req.body.title || !req.body.author || !req.body.isbn) {
    return res.status(400).json({ message: 'Titel, Autor und ISBN sind Pflichtfelder' });
  }
 
  const newBook = Book.create(req.body);
  res.status(201).json(newBook);
});

/**
 * @swagger
 * /api/books/{id}:
 * put:
* summary: Buch aktualisieren
* description: Aktualisiert die Informationen eines bestimmten Buchs anhand der ID
 * parameters:
 *       - in: path
 * name: id
 * required: true
 * schema:
 * type: integer
* description: Buch-ID
 * requestBody:
 * required: true
 * content:
 * application/json:
 * schema:
 * type: object
 * properties:
 * title:
 * type: string
 * author:
 * type: string
 * publishDate:
 * type: string
 * format: date
 * isbn:
 * type: string
 * category:
 * type: string
 * responses:
 *       200:
* description: Buch erfolgreich aktualisiert
 * content:
 * application/json:
 * schema:
 * $ref: '#/components/schemas/Book'
 *       404:
* description: Buch nicht gefunden
 */

router.put('/:id', (req, res) => {
  const id = parseInt(req.params.id);
  const updatedBook = Book.update(id, req.body);
 
  if (updatedBook) {
    res.json(updatedBook);
  } else {
    res.status(404).json({ message: 'Book not found' });
  }
});

/**
 * @swagger
 * /api/books/{id}:
 * delete:
* summary: Ein Buch löschen
* description: Ein bestimmtes Buch anhand der ID löschen
 * parameters:
 *       - in: path
 * name: id
 * required: true
 * schema:
 * type: integer
* description: Buch-ID
 * responses:
 *       200:
* description: Buch erfolgreich gelöscht
 *       404:
* description: Buch nicht gefunden
 */

router.delete('/:id', (req, res) => {
  const id = parseInt(req.params.id);
  const deletedBook = Book.delete(id);
 
  if (deletedBook) {
    res.json({ message: 'Buch erfolgreich gelöscht', book: deletedBook });
  } else {
    res.status(404).json({ message: 'Book not found' });
  }
});

module.exports = router;

Swagger-Dokumentationskonfiguration

Swagger konfigurieren

Erstelleswagger/swagger.jsDatei:

Beispiel

// swagger/swagger.js
const swaggerJsdoc = require('swagger-jsdoc');

const options = {
  Definition: {
    openapi: '3.0.0',
    Info: {
      title: 'Buchverwaltungs-API',
      version: '1.0.0',
      description: 'Eine mit Express und Swagger erstellte Buchverwaltungssystem-API',
      contact: {
        name: 'Entwickler',
        email: 'dev@example.com'
      }
    },
    servers: [
      {
        url: 'http://localhost:3000',
        description: 'Entwicklungsserver'
      }
    ]
  },
  // Alle JS-Dateien mit Annotationen durchsuchen
  apis: ['./routes/*.js']
};

const swaggerSpec = swaggerJsdoc(options);

module.exports = swaggerSpec;

Authentifizierungs-Middleware hinzufügen

Erstellemiddleware/auth.js:

Beispiel

// middleware/auth.js
const jwt = require('jsonwebtoken');

// Einfache JWT-Authentifizierungs-Middleware
const authMiddleware = (req, res, next) => {
  const token = req.header('Authorization')?.replace('Bearer ', '');
 
  if (!token) {
    return res.status(401).json({ message: 'Kein Authentifizierungstoken angegeben' });
  }
 
  try {
    // In einer echten Anwendung müssen Sie das JWT-Token hier verifizieren
    // const decoded = jwt.verify(token, process.env.JWT_SECRET);
    // req.user = decoded.user;
   
    // Um das Tutorial zu vereinfachen, überspringen wir die Verifizierung
    req.user = { id: 1, role: 'admin' };
    next();
  } catch (error) {
    return res.status(401).json({ message: 'Ungültiges Authentifizierungstoken' });
  }
};

module.exports = authMiddleware;

Funktionale API-Tests

Server starten

Verwenden Sie den folgenden Befehl, um den Server zu starten:

# 如果已配置了package.json中的scripts,执行:
npm start

# 或者直接使用nodemon
npx nodemon app.js

6.2 Zugriff auf die Swagger-Dokumentation

Öffnen Sie einen Browser und besuchen Sie: http://localhost:3000/api-docs

Verwenden Sie Swagger zum Testen von APIs

  1. Alle Bücher abrufen

    • Klicken Sie auf den Endpunkt GET /api/books
    • Klicken Sie auf die Schaltfläche "Try it out"
    • Sie können die Paginierungsparameter page und limit sowie Filterbedingungen festlegen
    • Klicken Sie auf die Schaltfläche "Execute", um die Anforderung zu senden
    • Beobachten Sie die Ergebnisse
  2. Ein neues Buch erstellen

    • Klicke auf den Endpunkt POST /api/books
    • Klicken Sie auf die Schaltfläche "Try it out"
    • Trage die Buchinformationen in den Request-Body ein, zum Beispiel:

      {
          "title": "RESTful API设计",
          "author": "Martin Fowler",
          "publishDate": "2020-01-01",
          "isbn": "978-1234567890",
          "category": "编程"
      }
      
    • Klicken Sie auf die Schaltfläche "Execute", um die Anforderung zu senden
    • Beobachten Sie die Ergebnisse
  3. Abrufen, Aktualisieren und Löschen

    • Teste andere Endpunkte mit ähnlichen Methoden

Fehlerbehebung bei häufigen Problemen

Cross-Origin-Problem

Wenn die Frontend-Anwendung und die API nicht auf derselben Domain laufen, können Cross-Origin-Probleme auftreten. Wir haben bereits CORS-Middleware am Einstiegspunkt der Anwendung konfiguriert:

app.use(cors());

Wenn eine feinere Kontrolle erforderlich ist, kannst du es so konfigurieren:

Beispiel

const corsOptions = {
  origin: ['http://localhost:8080', 'https://your-frontend-domain.com'],
  methods: ['GET', 'POST', 'PUT', 'DELETE'],
  allowedHeaders: ['Content-Type', 'Authorization'],
  credentials: true
};

app.use(cors(corsOptions));

Fehler in der Authentifizierungskonfiguration

Authentifizierungsprobleme treten normalerweise in den folgenden Bereichen auf:

  1. JWT-Konfigurationsfehler

    Stellen Sie sicherJWT_SECRETUmgebungsvariablen sind korrekt gesetzt:

    // 在应用启动时检查
    if (!process.env.JWT_SECRET) {
      console.warn('警告: JWT_SECRET环境变量未设置,认证可能不安全');
    }        
    
  2. Authentifizierungs-Middleware falsch verwendet

    Stellen Sie sicher, dass die Middleware korrekt auf Routen angewendet wird, die eine Authentifizierung erfordern:

    const auth = require('../middleware/auth');
    
    // 公开路由 - 无需认证
    router.get('/', (req, res) => { /* ... */ });
    
    // 受保护路由 - 需要认证
    router.post('/', auth, (req, res) => { /* ... */ });
    router.put('/:id', auth, (req, res) => { /* ... */ });
    router.delete('/:id', auth, (req, res) => { /* ... */ });
    
  3. Authentifizierungskonfiguration in der Swagger-Dokumentation

    Aktualisieren Sie die Swagger-Konfiguration, um die Bearer-Token-Authentifizierung zu unterstützen:

    // swagger/swagger.js
    const options = {
      definition: {
        // ... 其他配置 ...
        components: {
          securitySchemes: {
            bearerAuth: {
              type: 'http',
              scheme: 'bearer',
              bearerFormat: 'JWT'
            }
          }
        },
        security: [
          {
            bearerAuth: []
          }
        ]
      },
      // ... 其他配置 ...
    };
    
  4. Request-Header-Konfiguration

    Stellen Sie sicher, dass der Client den Authentifizierungs-Header bei Anfragen korrekt setzt:

    // 前端示例代码 - 使用fetch API
    const token = localStorage.getItem('token');
    
    fetch('http://localhost:3000/api/books', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${token}`
      },
      body: JSON.stringify(bookData)
    })
    .then(response => response.json())
    .then(data => console.log(data))
    .catch(error => console.error('错误:', error));
    

Swagger-Dokumentation wird nicht aktualisiert

Wenn Sie JSDoc-Kommentare aktualisieren, die Swagger-Dokumentation jedoch nicht aktualisiert wird, versuchen Sie die folgenden Lösungen:

  1. Stellen Sie sicher, dass die Pfadkonfiguration korrekt ist

    // swagger/swagger.js
    const options = {
      // ... 其他配置 ...
      apis: ['./routes/*.js', './models/*.js'] // 确保包含所有需要生成文档的文件
    };
    
  2. Server neu starten

    Manchmal müssen Sie den Server neu starten, um die neue Swagger-Dokumentation zu sehen.

  3. Browser-Cache leeren

    Verwenden Sie Ctrl+F5, um die Seite zwangsweise neu zu laden.


Erweiterte Funktionen

API-Versionierung hinzufügen

Ändern Sie die Einstiegsdatei der Anwendung:

// app.js
// ... 其他导入 ...

// API v1
app.use('/api/v1/books', booksRouter);

// 为未来的API v2预留
// app.use('/api/v2/books', booksRouterV2);

// ... 其他代码 ...

Anfragevalidierung hinzufügen

Verwenden Sie Express-Validierungsmiddleware (wie z. B.express-validator):

npm install express-validator --save

Verwenden Sie sie dann in der Route:

Beispiel

// routes/books.js
const { body, validationResult } = require('express-validator');

// Validierungsregeln zum Erstellen eines Buches
const validateBook = [
  body('title').notEmpty().withMessage('Titel darf nicht leer sein'),
  body('author').notEmpty().withMessage('Autor darf nicht leer sein'),
  body('isbn').notEmpty().withMessage('ISBN darf nicht leer sein')
    .matches(/^(?=(?:\D*\d){10}(?:(?:\D*\d){3})?$)[\d-]+$/).withMessage('Ungültiges ISBN-Format'),
  body('publishDate').optional().isDate().withMessage('Ungültiges Format für das Veröffentlichungsdatum'),
 
  // Middleware zur Verarbeitung von Validierungsergebnissen
  (req, res, next) => {
    const errors = validationResult(req);
    if (!errors.isEmpty()) {
      return res.status(400).json({ errors: errors.array() });
    }
    next();
  }
];

// Validierung in Routen verwenden
router.post('/', validateBook, (req, res) => {
  // ... Code zum Erstellen eines Buches ...
});

Antwortkomprimierung hinzufügen

Komprimierungs-Middleware verwenden, um die Antwortgröße zu reduzieren:

npm install compression --save

Fügen Sie sie dann der Einstiegsdatei der Anwendung hinzu:

// app.js
const compression = require('compression');

// ... 其他代码 ...

// 启用压缩
app.use(compression());

// ... 其他代码 ...

Antwort-Caching hinzufügen

Um die Leistung zu verbessern, können Sie Antwort-Caching hinzufügen:

npm install apicache --save

Verwenden Sie es dann am Einstiegspunkt der Anwendung:

// app.js
const apicache = require('apicache');
const cache = apicache.middleware;

// ... 其他代码 ...

// 缓存GET请求5分钟
app.use('/api', cache('5 minutes'));

// ... 其他代码 ...

Ratenbegrenzung für Anfragen hinzufügen

API-Missbrauch verhindern:

npm install express-rate-limit --save

Verwenden Sie es dann am Einstiegspunkt der Anwendung:

// app.js
const rateLimit = require('express-rate-limit');

// ... 其他代码 ...

// 创建限流中间件
const apiLimiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15分钟
  max: 100, // 每个IP在windowMs时间内最多100个请求
  message: '来自此IP的请求过多,请稍后再试'
});

// 应用限流中间件
app.use('/api', apiLimiter);

// ... 其他代码 ...
Weitere Erweiterungen