✍️Editor + Live-Vorschau

Links YAML oder JSON, rechts eine selbst gebaute Dokumentation – ohne Swagger UI, ohne Server. Jede Änderung wird sofort geparst (npm yaml), gegen die Regeln geprüft und die Schemas mit Ajv (JSON Schema 2020-12) validiert. Ein Klick auf ein Problem springt zur Zeile.

openapi.yaml · 316 Zeilen✅ gültig

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

249

250

251

252

253

254

255

256

257

258

259

260

261

262

263

264

265

266

267

268

269

270

271

272

273

274

275

276

277

278

279

280

281

282

283

284

285

286

287

288

289

290

291

292

293

294

295

296

297

298

299

300

301

302

303

304

305

306

307

308

309

310

311

312

313

314

315

316

openapi: 3.1.1
info:
  title: Buchladen-API
  summary: Bücher suchen, anlegen und bestellen
  description: Beispiel-API der App VisualOpenApi – alle Daten sind erfunden.
  version: 1.2.0
  license:
    name: MIT
    identifier: MIT
servers:
  - url: https://api.example.org/v1
    description: Produktion
  - url: http://localhost:4010
    description: Lokaler Mock-Server (z. B. Prism)
tags:
  - name: Bücher
    description: Katalog lesen und pflegen
  - name: Bestellungen
    description: Warenkorb abschicken
security:
  - apiKey: []
paths:
  /books:
    get:
      operationId: listBooks
      tags: [Bücher]
      summary: Bücher auflisten
      security: []   # öffentlich – überschreibt das globale security
      parameters:
        - name: q
          in: query
          description: Suchbegriff (Titel oder Autor)
          schema:
            type: string
            minLength: 2
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: Trefferliste
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Book'
              example:
                - id: 42
                  title: Per Anhalter durch die API
                  author: { name: Ada Beispiel }
                  price: 12.5
                  subtitle: null
    post:
      operationId: createBook
      tags: [Bücher]
      summary: Buch anlegen
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewBook'
            example:
              title: Das Schema-Handbuch
              author: { name: Bert Muster }
              price: 29.9
      responses:
        '201':
          description: Angelegt
          headers:
            Location:
              description: URL des neuen Buchs
              schema: { type: string, format: uri }
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Book'
              example:
                id: 1001
                title: Das Schema-Handbuch
                author: { name: Bert Muster }
                price: 29.9
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /books/bestseller:
    get:
      operationId: listBestsellers
      tags: [Bücher]
      summary: Die fünf meistverkauften Bücher
      security: []
      responses:
        '200':
          description: Bestseller
          content:
            application/json:
              schema:
                type: array
                maxItems: 5
                items:
                  $ref: '#/components/schemas/Book'
  /books/{bookId}:
    parameters:
      - $ref: '#/components/parameters/BookId'
    get:
      operationId: getBook
      tags: [Bücher]
      summary: Ein Buch lesen
      security: []
      responses:
        '200':
          description: Das Buch
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Book'
              example:
                id: 42
                title: Per Anhalter durch die API
                author: { name: Ada Beispiel, born: 1970 }
                price: 12.5
                subtitle: null
                category: { name: Science-Fiction, parent: { name: Romane } }
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteBook
      tags: [Bücher]
      summary: Buch löschen (nur Admins)
      security:
        - bearerAuth: []
      responses:
        '204':
          description: Gelöscht
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /orders:
    post:
      operationId: createOrder
      tags: [Bestellungen]
      summary: Bestellung aufgeben
      security:
        - oauth: [orders:write]
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Order'
            example:
              items:
                - { bookId: 42, quantity: 2 }
      responses:
        '201':
          description: Bestellung angenommen
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
              example:
                id: 7
                status: offen
                items:
                  - { bookId: 42, quantity: 2 }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
webhooks:
  orderShipped:
    post:
      summary: Wir rufen Ihre URL auf, sobald eine Bestellung versandt ist
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Order'
      responses:
        '200':
          description: Empfang bestätigt
components:
  schemas:
    NewBook:
      type: object
      required: [title, author, price]
      properties:
        title:
          type: string
          minLength: 1
          maxLength: 200
        subtitle:
          type: [string, 'null']
          description: Untertitel oder null
        isbn:
          type: string
          pattern: '^97[89][0-9]{10}$'
        author:
          $ref: '#/components/schemas/Author'
        price:
          type: number
          minimum: 0
          description: Preis in Euro
        category:
          $ref: '#/components/schemas/Category'
    Book:
      description: Ein Buch im Katalog (NewBook plus Server-Felder)
      allOf:
        - $ref: '#/components/schemas/NewBook'
        - type: object
          required: [id]
          properties:
            id:
              type: integer
              format: int64
              minimum: 1
              readOnly: true
    Author:
      type: object
      required: [name]
      properties:
        name: { type: string }
        born: { type: integer, minimum: 1000, maximum: 2100 }
    Category:
      description: Rekursiv – eine Kategorie kann eine Oberkategorie haben
      type: object
      required: [name]
      properties:
        name: { type: string }
        parent:
          $ref: '#/components/schemas/Category'
    Order:
      type: object
      required: [items]
      properties:
        id:
          type: integer
          readOnly: true
        status:
          type: string
          enum: [offen, versandt, storniert]
          readOnly: true
        items:
          type: array
          minItems: 1
          items:
            type: object
            required: [bookId, quantity]
            properties:
              bookId: { type: integer, minimum: 1 }
              quantity: { type: integer, minimum: 1, maximum: 10 }
    Problem:
      description: Fehlerformat nach RFC 9457 (Problem Details)
      type: object
      properties:
        type: { type: string, format: uri-reference }
        title: { type: string }
        status: { type: integer }
        detail: { type: string }
  parameters:
    BookId:
      name: bookId
      in: path
      required: true
      description: Kennung des Buchs
      schema:
        type: integer
        minimum: 1
    Limit:
      name: limit
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
  responses:
    NotFound:
      description: Nicht gefunden
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    BadRequest:
      description: Anfrage ungültig
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Unauthorized:
      description: Anmeldung fehlt
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    oauth:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://auth.example.org/authorize
          tokenUrl: https://auth.example.org/token
          scopes:
            orders:write: Bestellungen aufgeben
            books:read: Katalog lesen

Buchladen-API

v1.2.0OAS 3.1.1

Bücher suchen, anlegen und bestellen

Beispiel-API der App VisualOpenApi – alle Daten sind erfunden.

🌐 https://api.example.org/v1 · Produktion🌐 http://localhost:4010 · Lokaler Mock-Server (z. B. Prism)

Bücher – Katalog lesen und pflegen

Bestellungen – Warenkorb abschicken

🪝 Webhooks – die API ruft Sie auf

🧬 Schemas

NewBook

title *	stringLänge ≥ 1 · Länge ≤ 200
subtitle	string \| null Untertitel oder null
isbn	stringMuster "^97[89][0-9]{10}$"
author *
price *	number≥ 0 Preis in Euro
category

Book

allOf (alle zusammen)

id *	integer (int64)≥ 1 · nur lesen

Author

name *	string
born	integer≥ 1000 · ≤ 2100

📋Welche Regeln werden geprüft?

Eine Auswahl der Fehler, an denen man in der Praxis am häufigsten scheitert. Für vollständige Prüfungen im Build eignen sich Spectral oder Redocly CLI (siehe „Code & Werkzeuge“).

Regel	Stufe	Worum geht es?
openapi-feld	⛔ Fehler	`openapi` fehlt oder ist keine Version 3.0.x/3.1.x/3.2.x
swagger-2	⛔ Fehler	Swagger-2.0-Datei erkannt (`swagger: "2.0"`)
info-pflicht	⛔ Fehler	`info`, `info.title` und `info.version` sind Pflicht
inhalt-pflicht	⛔ Fehler	3.0: `paths` ist Pflicht · ab 3.1: mindestens `paths`, `components` oder `webhooks`
pfad-slash	⛔ Fehler	Pfade müssen mit `/` beginnen
pfadparameter-fehlt	⛔ Fehler	`{name}` im Pfad ohne passenden Parameter `in: path`
pfadparameter-unbenutzt	⛔ Fehler	Parameter `in: path`, der im Pfad-Template nicht vorkommt
pfadparameter-required	⛔ Fehler	Pfadparameter brauchen `required: true`
parameter-form	⛔ Fehler	Parameter: `name`, gültiges `in` und genau eines von `schema`/`content`
parameter-doppelt	⛔ Fehler	Gleicher Parameter (name + in) mehrfach in einer Operation
operationid-doppelt	⛔ Fehler	`operationId` muss im ganzen Dokument eindeutig sein
responses	⚠️ Warnung	Operation ohne `responses` (3.0: Pflicht, ab 3.1 optional, aber üblich)
response-beschreibung	⛔ Fehler	Response ohne `description` (bis 3.1 Pflicht, ab 3.2 optional)
statuscode	⛔ Fehler	Statuscode muss 100–599, `1XX`…`5XX` oder `default` sein
ref-unbekannt	⛔ Fehler	`$ref` zeigt auf ein nicht vorhandenes Ziel
ref-extern	ℹ️ Hinweis	Externer `$ref` – wird im Browser nicht nachgeladen
ref-geschwister	⚠️ Warnung	Felder neben `$ref`, die ignoriert werden
nullable	⚠️ Warnung	`nullable` gibt es ab 3.1 nicht mehr – `type: [string, "null"]` verwenden
schema	⛔ Fehler	Schema verletzt JSON Schema 2020-12 (z. B. `type: strin`)
beispiel	⚠️ Warnung	Beispiel passt nicht zum eigenen Schema
security-unbekannt	⛔ Fehler	Security-Anforderung nennt ein nicht definiertes Schema
security-schema	⛔ Fehler	Security Scheme unvollständig (z. B. apiKey ohne `name`/`in`)
tag-undeklariert	ℹ️ Hinweis	Operation nutzt einen Tag, der oben unter `tags` fehlt
get-body	⚠️ Warnung	GET/HEAD/DELETE mit `requestBody` – viele Werkzeuge ignorieren das
versionsfeature	⛔ Fehler	Feld aus einer neueren Version (`webhooks` < 3.1, `query`/`$self` < 3.2)
server-url	⛔ Fehler	Server-Eintrag ohne `url`

type	string (uri-reference)
title	string
status	integer
detail	string