Zuletzt aktualisiert: 11. September

Datei-Upload-APIs mit Swagger und OpenAPI dokumentieren

Kevin van Zonneveld

Mitgründer · Amsterdam, Niederlande ·

Die Dokumentation Ihrer APIs für Datei-Uploads und Downloads ist entscheidend für Wartbarkeit und einfache Nutzung in Webdiensten. In diesem Beitrag zeigen wir, wie Sie Ihre Datei-APIs mit Swagger und der OpenAPI-Spezifikation effektiv dokumentieren, damit Entwickler nahtlos mit Ihren RESTful-Diensten interagieren können.

Einführung

In der modernen Webentwicklung sind Datei-APIs entscheidend für die Abwicklung von Datei-Uploads und Downloads in Webdiensten. Eine klare Dokumentation ist unerlässlich, damit Entwickler diese Endpunkte schnell integrieren und pflegen können. Dieser Leitfaden zeigt, wie Sie Ihre Endpunkte für Datei-Uploads und Downloads mit den Swagger-Werkzeugen und der OpenAPI-Spezifikation dokumentieren. So erstellen Sie eine interaktive und standardisierte Dokumentation für Ihre REST API.

Datei-APIs verstehen

Was ist eine Datei-API?

Eine Datei-API ist eine Sammlung programmatischer Schnittstellen, die das Hochladen und Herunterladen von Dateien über das Internet ermöglichen. Diese APIs erlauben es Clients, mit serverseitigen Ressourcen zu interagieren, um Dateien wie Bilder, Dokumente oder beliebige Binärdaten zu speichern und abzurufen. Gut entworfene Datei-APIs sind unverzichtbar für Webdienste, die Dateiübertragungen abwickeln, und sorgen für eine effiziente und sichere Kommunikation zwischen Clients und Servern.

Was sind Swagger und OpenAPI?

OpenAPI ist ein sprachunabhängiger Standard zur Beschreibung von HTTP-APIs, der ursprünglich auf der Swagger-Spezifikation basiert. Swagger bezeichnet heute eine Reihe von Werkzeugen, die mit OpenAPI arbeiten. Dieses Beispiel verwendet OpenAPI 3.0.3, um Endpunkte, Parameter und Antworten zu beschreiben. Swagger UI und Swagger Editor können diese Definition nutzen, um interaktive Dokumentation bereitzustellen und das Testen zu vereinfachen.

Vorteile der API-Dokumentation

Bessere Entwicklererfahrung: Eine klare Dokumentation hilft Entwicklern zu verstehen, wie sie Ihre API ohne Verwirrung nutzen.
Standardisierung: Ein Standard wie OpenAPI fördert Konsistenz in Ihrer gesamten API-Dokumentation.
Automatische Dokumentationserstellung: Werkzeuge können aus Ihrer OpenAPI-Definition automatisch interaktive Dokumentation erzeugen.
Einfachere Wartung: Die Dokumentation lässt sich leichter aktualisieren, wenn sie in einem strukturierten, maschinenlesbaren Format definiert ist.
Besseres API-Testing: Entwickler können Werkzeuge wie Postman oder cURL nutzen, um Ihre Endpunkte für Datei-Uploads und Downloads effektiv zu testen.

Swagger in Ihrem Projekt einrichten

Für dieses Beispiel verwenden wir ein Node.js-Projekt mit Express.

Das Projekt initialisieren

mkdir file-api-swagger
cd file-api-swagger
npm init -y

Abhängigkeiten installieren

npm install express@4.22.2 swagger-ui-express@5.0.0 swagger-jsdoc@6.2.8 multer@2.3.0

Hinweis

Multer 2.3.0 enthält die Sicherheitsfixes vom August 2026. Halten Sie Upload-Abhängigkeiten gepatcht, sobald neue Sicherheitshinweise veröffentlicht werden.

Grundlegende Einrichtung des Express-Servers

Verwenden Sie Node.js 22 oder neuer. Erstellen Sie index.js und hinterlegen Sie über Ihre Umgebung einen starken Wert für FILE_API_KEY. Der API-Schlüssel gewährt Zugriff auf den gemeinsamen Dateispeicher dieser Demonstration; ein Dienst mit mehreren Nutzern benötigt zusätzlich Eigentumsprüfungen pro Datei. Fügen Sie nachfolgende Server-Snippets vor app.listen ein.

const express = require('express')
const { timingSafeEqual } = require('node:crypto')
const app = express()
const port = 3000

app.use(express.json())

const apiKey = process.env.FILE_API_KEY
if (!apiKey) throw new Error('FILE_API_KEY is required')
const expectedKey = Buffer.from(apiKey)

function requireApiKey(req, res, next) {
  const suppliedKey = Buffer.from(req.get('X-API-Key') || '')
  if (suppliedKey.length !== expectedKey.length || !timingSafeEqual(suppliedKey, expectedKey)) {
    return res.status(401).json({ error: 'Unauthorized' })
  }
  next()
}

app.use(['/upload', '/uploads', '/download'], requireApiKey)

app.listen(port, () => {
  console.log(`Server running at http://localhost:${port}`)
})

Endpunkte für Datei-Uploads dokumentieren

Multer für Datei-Uploads einrichten

const multer = require('multer')
const path = require('node:path')
const uploadsDir = path.join(__dirname, 'uploads')
const upload = multer({
  dest: uploadsDir,
  limits: {
    fileSize: 5 * 1024 * 1024, // 5MB limit
    files: 10,
    fields: 0,
  },
  fileFilter: (req, file, cb) => {
    const allowedTypes = ['image/jpeg', 'image/png', 'application/pdf']
    if (!allowedTypes.includes(file.mimetype)) {
      return cb(Object.assign(new Error('Unsupported file type'), { code: 'UNSUPPORTED_FILE_TYPE' }))
    }
    cb(null, true)
  },
})

Endpunkt für den Upload einer einzelnen Datei

app.post('/upload', upload.single('file'), (req, res) => {
  try {
    if (!req.file) {
      return res.status(400).json({ error: 'No file uploaded' })
    }
    res.json({
      message: 'File uploaded successfully',
      file: {
        id: req.file.filename,
        name: req.file.originalname,
        size: req.file.size,
        mimetype: req.file.mimetype,
      },
    })
  } catch (error) {
    res.status(500).json({ error: 'File upload failed' })
  }
})

Mit Swagger dokumentieren

Swagger-Konfiguration hinzufügen

Erstellen Sie die Datei swagger.js:

const swaggerJsDoc = require('swagger-jsdoc')
const swaggerUi = require('swagger-ui-express')

const swaggerDefinition = {
  openapi: '3.0.3',
  info: {
    title: 'File Upload API',
    version: '1.0.0',
    description: 'API documentation for file upload and download endpoints',
  },
  servers: [
    {
      url: 'http://localhost:3000',
    },
  ],
  components: {
    securitySchemes: {
      ApiKeyAuth: {
        type: 'apiKey',
        in: 'header',
        name: 'X-API-Key',
      },
    },
  },
}

const options = {
  swaggerDefinition,
  apis: ['./index.js'],
}

const swaggerSpec = swaggerJsDoc(options)

module.exports = {
  swaggerUi,
  swaggerSpec,
}

Swagger UI in den Server integrieren

In Ihrer Datei index.js:

const { swaggerUi, swaggerSpec } = require('./swagger')
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec))

Starten Sie Ihren Server:

node index.js

Rufen Sie http://localhost:3000/api-docs auf, um die interaktive Swagger-UI-Dokumentation anzuzeigen.

Swagger-Kommentare zur Dokumentation des Endpunkts hinzufügen

Platzieren Sie den folgenden Kommentar direkt über der bestehenden Route für den Upload einzelner Dateien in index.js. Registrieren Sie die Route kein zweites Mal. Die Deklaration von ApiKeyAuth dokumentiert die Anforderung; durchgesetzt wird sie tatsächlich von der Middleware requireApiKey weiter oben.

/**
 * @swagger
 * /upload:
 *   post:
 *     security:
 *       - ApiKeyAuth: []
 *     summary: Uploads a file.
 *     requestBody:
 *       required: true
 *       content:
 *         multipart/form-data:
 *           schema:
 *             type: object
 *             properties:
 *               file:
 *                 type: string
 *                 format: binary
 *     responses:
 *       200:
 *         description: File uploaded successfully.
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 message:
 *                   type: string
 *                 file:
 *                   type: object
 *                   properties:
 *                     id:
 *                       type: string
 *                     name:
 *                       type: string
 *                     size:
 *                       type: number
 *                     mimetype:
 *                       type: string
 *       400:
 *         description: No file uploaded
 *       401:
 *         description: Missing or invalid API key
 *       413:
 *         description: File exceeds the size limit
 *       415:
 *         description: Unsupported file type
 *       500:
 *         description: File upload failed
 */

Uploads mehrerer Dateien

/**
 * @swagger
 * /uploads:
 *   post:
 *     security:
 *       - ApiKeyAuth: []
 *     summary: Uploads multiple files.
 *     requestBody:
 *       required: true
 *       content:
 *         multipart/form-data:
 *           schema:
 *             type: object
 *             properties:
 *               files:
 *                 type: array
 *                 items:
 *                   type: string
 *                   format: binary
 *     responses:
 *       200:
 *         description: Files uploaded successfully.
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 message:
 *                   type: string
 *                 files:
 *                   type: array
 *                   items:
 *                     type: object
 *                     properties:
 *                       id:
 *                         type: string
 *                       name:
 *                         type: string
 *                       size:
 *                         type: number
 *                       mimetype:
 *                         type: string
 *       400:
 *         description: Missing files or invalid upload
 *       401:
 *         description: Missing or invalid API key
 *       413:
 *         description: A file exceeds the size limit
 *       415:
 *         description: Unsupported file type
 */
app.post('/uploads', upload.array('files', 10), (req, res) => {
  try {
    if (!req.files || req.files.length === 0) {
      return res.status(400).json({ error: 'No files uploaded' })
    }
    res.json({
      message: 'Files uploaded successfully',
      files: req.files.map((file) => ({
        id: file.filename,
        name: file.originalname,
        size: file.size,
        mimetype: file.mimetype,
      })),
    })
  } catch (error) {
    res.status(500).json({ error: 'File upload failed' })
  }
})

Datei-Upload-APIs mit Postman testen

Postman ist ein beliebtes Werkzeug zum Testen von APIs, einschließlich Endpunkten für Datei-Uploads. So testen Sie Ihre Endpunkte für Datei-Uploads:

Öffnen Sie Postman und erstellen Sie eine neue POST-Anfrage.
Geben Sie die URL Ihres API-Endpunkts ein (z. B. http://localhost:3000/upload).
Wählen Sie im Tab „Body“ die Option form-data und fügen Sie einen Schlüssel mit dem Namen file hinzu.
Ändern Sie den Typ des Schlüssels file auf „File“ und wählen Sie eine Datei aus Ihrem System aus.
Fügen Sie den Header X-API-Key mit Ihrem API-Schlüssel hinzu.
Senden Sie die Anfrage und betrachten Sie die Antwort.

Alternativ können Sie mit cURL testen:

curl -fsSL -F 'file=@/path/to/your/file.jpg' -H 'X-API-Key: YOUR_API_KEY' http://localhost:3000/upload

Endpunkte für Datei-Downloads dokumentieren

Verwenden Sie den generierten Wert id, den ein Upload zurückgibt, als filename und nicht den ursprünglichen Dateinamen des Clients. Die Allowlist und die Express-Option root verhindern, dass Anfragen Dateien außerhalb des Upload-Verzeichnisses auswählen. Der MIME-Filter von Multer vertraut den Metadaten des Clients, daher bleiben Dateien private Downloads und keine öffentlich ausführbaren Inhalte. Prüfen Sie Inhalte vor der Verarbeitung mit einem geeigneten Parser/Scanner.

/**
 * @swagger
 * /download/{filename}:
 *   get:
 *     security:
 *       - ApiKeyAuth: []
 *     summary: Downloads a file.
 *     parameters:
 *       - in: path
 *         name: filename
 *         required: true
 *         schema:
 *           type: string
 *         description: Generated file ID returned by an upload.
 *     responses:
 *       200:
 *         description: File downloaded successfully.
 *         content:
 *           application/octet-stream:
 *             schema:
 *               type: string
 *               format: binary
 *       404:
 *         description: File not found
 *       401:
 *         description: Missing or invalid API key
 *       500:
 *         description: Download failed
 */
app.get('/download/:filename', (req, res, next) => {
  if (!/^[a-f0-9]{32}$/.test(req.params.filename)) {
    return res.status(404).json({ error: 'File not found' })
  }
  res.download(req.params.filename, { root: uploadsDir }, (error) => {
    if (!error) return
    if (res.headersSent) return next(error)
    res.status(404).json({ error: 'File not found' })
  })
})

// Register after all routes, including both upload routes.
app.use((error, req, res, next) => {
  if (res.headersSent) return next(error)
  if (error.code === 'UNSUPPORTED_FILE_TYPE') {
    return res.status(415).json({ error: 'Unsupported file type' })
  }
  if (error instanceof multer.MulterError) {
    return res.status(error.code === 'LIMIT_FILE_SIZE' ? 413 : 400).json({ error: 'Upload rejected' })
  }
  console.error('File API request failed')
  res.status(500).json({ error: 'File request failed' })
})

Sicherheitsaspekte

Verwaltung von API-Schlüsseln

Die Middleware für den API-Schlüssel muss vor der Verarbeitung von Uploads laufen. Rate Limiting ergänzt eine separate Missbrauchskontrolle; es ist keine Authentifizierung. Installieren Sie die optionale Middleware:

npm install express-rate-limit@8 helmet@8

Registrieren Sie den Limiter vor den Routen und der Upload-Middleware, nicht danach:

const { rateLimit } = require('express-rate-limit')

const limiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 100, // limit each IP to 100 requests per window
})

app.use(limiter)

Sichere Dateiübertragungen

Beachten Sie für sichere Dateiübertragungen diese bewährten Verfahren:

Verwenden Sie HTTPS für alle API-Endpunkte, um Daten während der Übertragung zu verschlüsseln.
Nutzen Sie Middleware wie Helmet, um sichere HTTP-Header zu setzen.
Validieren Sie Dateitypen und erzwingen Sie Größenbeschränkungen für Dateien, wie in der Multer-Konfiguration gezeigt.
Aktualisieren Sie Abhängigkeiten regelmäßig und beobachten Sie Sicherheitshinweise.

Setzen Sie beispielsweise Sicherheits-Header für die Datei-API, bevor Sie deren Routen registrieren. Halten Sie die Seitenrichtlinie von Swagger UI davon getrennt und konfigurieren Sie sie für die Assets/Skripte, die Ihr Deployment tatsächlich verwendet:

const helmet = require('helmet')
app.use(['/upload', '/uploads', '/download'], helmet())

Fazit

Die Dokumentation Ihrer APIs für Datei-Uploads und Downloads mit Swagger und der OpenAPI-Spezifikation verdeutlicht nicht nur, wie man mit Ihren Diensten interagiert, sondern vereinfacht auch Wartung und Tests. In diesem Leitfaden haben wir einen Express-Server eingerichtet, Swagger für interaktive Dokumentation integriert und grundlegende Sicherheitsmaßnahmen umgesetzt. Für fortgeschrittenere Lösungen im Umgang mit Dateien lohnt sich ein Blick auf Uppy, das moderne, modulare Ansätze für Datei-Uploads bietet.

Viel Spaß beim Programmieren!