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 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
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
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
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
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
-
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
-
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
-
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
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:
-
JWT-Konfigurationsfehler
Stellen Sie sicher
JWT_SECRETUmgebungsvariablen sind korrekt gesetzt:// 在应用启动时检查 if (!process.env.JWT_SECRET) { console.warn('警告: JWT_SECRET环境变量未设置,认证可能不安全'); } -
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) => { /* ... */ }); -
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: [] } ] }, // ... 其他配置 ... }; -
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:
-
Stellen Sie sicher, dass die Pfadkonfiguration korrekt ist
// swagger/swagger.js const options = { // ... 其他配置 ... apis: ['./routes/*.js', './models/*.js'] // 确保包含所有需要生成文档的文件 }; -
Server neu starten
Manchmal müssen Sie den Server neu starten, um die neue Swagger-Dokumentation zu sehen.
-
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
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