# Handleiding voor het automatiseren van documentatieprocessen voor REST API Documentatie Deze handleiding beschrijft stapsgewijs hoe je het automatiseren van documentatieprocessen voor REST API's kunt implementeren. Ze is bedoeld voor softwareontwikkelaars met basiskennis en bevat praktische voorbeelden, benodigde tools, integratiestappen, workflows en kwaliteitscontroles. --- ## Inhoudsopgave 1. Benodigdheden en tools 2. Voorbereiding en projectstructuur 3. Automatiseren van API-specificatie genereren 4. Genereren van documentatie 5. Integratie in CI/CD pipeline 6. Kwaliteitscontroles en validatie 7. Voorbeeld workflow 8. Conclusie --- ## 1. Benodigdheden en tools ### 1.1 Programmeertalen en frameworks - Programmeertaal: **JavaScript (Node.js)** of **Python** (keuze afhankelijk van project) - API-definitie: **OpenAPI (Swagger)** specificaties ### 1.2 Tools | Tool | Functie | Beschrijving | |---|---|---| | **Swagger/OpenAPI** | API-specificatie | Beschrijft REST API's in een gestructureerd formaat | | **Swagger Editor** | Handmatige specificatie | Voor het ontwerpen en valideren van API-specificaties | | **Swagger Codegen / OpenAPI Generator** | Code en documentatie genereren | Automatiseert de generatietaken voor client, server en documentatie | | **Redoc / Swagger UI** | API documentatie visualisatie | Voor het tonen van interactieve API-documentatie | | **CI/CD tools (Jenkins, GitHub Actions, GitLab CI)** | Automatisering | Voor integratie en deployment workflows | | **Version control (Git)** | Versiebeheer | Voor broncode en documentatie beheer | --- ## 2. Voorbereiding en projectstructuur ### 2.1 Structuur opzetten Maak een projectmap met de volgende structuur: ``` /project-root |-- api-specs/ | |-- openapi.yaml |-- scripts/ | |-- generate-docs.js (of .py) |-- docs/ | |-- index.html |-- .gitignore |-- README.md ``` ### 2.2 API-specificatie maken Gebruik **Swagger Editor** om je API te beschrijven in `openapi.yaml`. Bijvoorbeeld: ```yaml openapi: 3.0.0 info: title: Voorbeeld API version: 1.0.0 paths: /gebruikers: get: summary: Lijst van gebruikers responses: '200': description: Succes content: application/json: schema: type: array items: $ref: '#/components/schemas/Gebruiker' components: schemas: Gebruiker: type: object properties: id: type: integer naam: type: string ``` ### 2.3 Validatie Gebruik **Swagger Editor** of CLI-tools om je specificaties te valideren. --- ## 3. Automatiseren van API-specificatie genereren ### 3.1 Genereren van documentatie met OpenAPI Generator Installeer de OpenAPI Generator: ```bash npm install @openapitools/openapi-generator-cli -g ``` ### 3.2 Generatie commando Maak een script (bijv. `scripts/generate-docs.js`) dat de documentatie genereert: ```bash openapi-generator generate -i ../api-specs/openapi.yaml -g html -o ../docs ``` Hiermee wordt een HTML-documentatie gegenereerd in de `docs/` directory. ### 3.3 Automatiseren Voeg dit commando toe aan je build- of CI/CD script, zodat documentatie automatisch wordt bijgewerkt bij elke commit. --- ## 4. Genereren van documentatie ### 4.1 Interactieve documentatie Gebruik **Redoc** of **Swagger UI**: - **Redoc**: Plaats `redoc-cli` in je buildproces: ```bash redoc-cli bundle ../api-specs/openapi.yaml -o ../docs/index.html ``` - **Swagger UI**: Implementeer in je website of laat de standaard UI genereren door OpenAPI Generator. ### 4.2 Automatisering Integreer in je CI/CD pipeline: ```bash # Voor Redoc redoc-cli bundle ../api-specs/openapi.yaml -o ../docs/index.html # Commit en push git add ../docs/index.html git commit -m "Automatische bijwerking API documentatie" git push origin main ``` --- ## 5. Integratie in CI/CD pipeline ### 5.1 Voorbeeld GitHub Actions workflow ```yaml name: API Documentatie Generatie on: push: branches: - main jobs: build-docs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - name: Installeer Node.js uses: actions/setup-node@v2 with: node-version: '14' - name: Installeer OpenAPI Generator run: npm install @openapitools/openapi-generator-cli -g - name: Genereer documentatie run: | openapi-generator generate -i api-specs/openapi.yaml -g html -o docs/ - name: Commit en push documentatie run: | git config --global user.name 'CI Bot' git config --global user.email 'ci@bot.com' git add docs/ git commit -m "Automatische update API documentatie" git push ``` --- ## 6. Kwaliteitscontroles en validatie ### 6.1 Validatie van API-specificaties Gebruik CLI-tools zoals: ```bash swagger-cli validate api-specs/openapi.yaml ``` of ```bash speccy lint api-specs/openapi.yaml ``` ### 6.2 Validatie van gegenereerde documentatie Controleer of gegenereerde HTML correct wordt weergegeven en alle endpoints correct zijn gedocumenteerd. ### 6.3 Automatische tests - Controleer of de API-implementatie overeenkomt met de specificatie. - Gebruik contract testing tools zoals **Prism** of **Dredd**. --- ## 7. Praktisch voorbeeld workflow 1. **API-specificatie bijwerken**: Ontwikkelaar past `openapi.yaml` aan. 2. **Commit en push**: Veranderingen worden gecommit. 3. **CI/CD pipeline start**: - Validatie van specificatie. - Generatie van nieuwe documentatie. - Automatisch committen en publiceren. 4. **Publicatie**: Nieuwe documentatie wordt automatisch beschikbaar op de website. --- ## 8. Conclusie Door gebruik te maken van tools zoals OpenAPI Generator en CI/CD integraties, kunnen ontwikkelaars effectief en consistent API-documentatie automatiseren. Dit vermindert handmatig werk, minimaliseert fouten en zorgt dat documentatie altijd actueel is. --- Heeft u verdere vragen of wenst u hulp bij het opzetten van een specifiek onderdeel?

# Technische Handleiding: Automatiseren van REST API Documentatieprocessen ## 1. Inleiding Deze handleiding beschrijft een complete workflow voor het automatiseren van REST API documentatie. We richten ons op het opzetten van een geautomatiseerd systeem dat documentatie genereert vanuit broncode, beheert en publiceert met minimale handmatige interventie. ## 2. Benodigde Tools en Technologieën ### 2.1 Documentatie Generatoren - **OpenAPI/Swagger**: Standaard specificatie voor REST API's - **Swagger UI**: Web-based interface voor API documentatie - **ReDoc**: Alternatieve documentatie renderer - **SpringDoc OpenAPI** (voor Java) of **Swashbuckle** (voor .NET) ### 2.2 Build Tools en CI/CD - **Maven/Gradle** (Java) of **npm** (Node.js) - **Jenkins**, **GitLab CI**, of **GitHub Actions** - **Docker** voor containerisatie ### 2.3 Versiebeheer en Hosting - **Git** voor versiebeheer - **GitHub Pages**, **GitLab Pages**, of **AWS S3** voor hosting ## 3. Implementatiestappen ### 3.1 OpenAPI Specificatie Setup ```yaml # openapi.yaml basis structuur openapi: 3.0.0 info: title: Example API version: 1.0.0 description: Geautomatiseerde API documentatie servers: - url: https://api.example.com/v1 paths: /users: get: summary: Lijst van gebruikers responses: '200': description: Succesvolle response content: application/json: schema: type: array items: $ref: '#/components/schemas/User' ``` ### 3.2 Code Annotaties (Java voorbeeld) ```java @RestController @RequestMapping("/api/v1") @Tag(name = "User Management", description = "User management endpoints") public class UserController { @Operation(summary = "Get user by ID", description = "Returns a single user") @ApiResponses(value = { @ApiResponse(responseCode = "200", description = "User found", content = @Content(schema = @Schema(implementation = User.class))), @ApiResponse(responseCode = "404", description = "User not found") }) @GetMapping("/users/{id}") public ResponseEntity<User> getUser(@Parameter(description = "User ID") @PathVariable Long id) { // Implementatie } } ``` ### 3.3 Build Configuration (Maven voorbeeld) ```xml <plugin> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-maven-plugin</artifactId> <version>1.4</version> <executions> <execution> <phase>compile</phase> <goals> <goal>generate</goal> </goals> </execution> </executions> </plugin> ``` ## 4. Automatisering Workflow ### 4.1 CI/CD Pipeline (GitHub Actions voorbeeld) ```yaml name: API Documentation Pipeline on: push: branches: [ main ] pull_request: branches: [ main ] jobs: generate-docs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - name: Set up Java uses: actions/setup-java@v2 with: java-version: '11' distribution: 'temurin' - name: Generate OpenAPI spec run: mvn compile springdoc:generate - name: Validate OpenAPI spec run: | npx @apidevtools/swagger-cli validate openapi.json npx speccy lint openapi.json - name: Build documentation site run: | npx redoc-cli build openapi.json -o docs/index.html - name: Deploy to GitHub Pages if: github.ref == 'refs/heads/main' uses: peaceiris/actions-gh-pages@v3 with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./docs ``` ### 4.2 Documentatie Generatie Script ```bash #!/bin/bash # generate-docs.sh echo "Starting documentation generation..." # Genereer OpenAPI specificatie mvn compile springdoc:generate # Valideer de gegenereerde specificatie npx @apidevtools/swagger-cli validate target/openapi.json # Bouw statische documentatie npx redoc-cli build target/openapi.json --output docs/index.html # Voeg kwaliteitscontroles uit npx speccy lint target/openapi.json echo "Documentation generation completed" ``` ## 5. Kwaliteitscontroles ### 5.1 Automatische Validatie ```yaml # .speccy.yaml - Linting configuratie rules: openapi-tags: error operation-tags: error info-contact: warning operation-description: warning tag-description: warning operation-operationId: error ``` ### 5.2 Custom Validatie Script ```javascript // validate-docs.js const OpenAPISchemaValidator = require('openapi-schema-validator').default; const validator = new OpenAPISchemaValidator({ version: 3 }); function validateOpenAPISpec(spec) { const result = validator.validate(spec); if (result.errors.length > 0) { console.error('OpenAPI validatiefouten:'); result.errors.forEach(error => { console.error(`- ${error.message}`); }); process.exit(1); } else { console.log('OpenAPI specificatie is valide'); } } // Gebruik const spec = require('./openapi.json'); validateOpenAPISpec(spec); ``` ## 6. Praktische Voorbeelden ### 6.1 Automatische Changelog Generatie ```python # generate-changelog.py import requests import json from datetime import datetime def generate_changelog(old_spec, new_spec): changes = [] # Vergelijk endpoints old_endpoints = set(old_spec['paths'].keys()) new_endpoints = set(new_spec['paths'].keys()) # Nieuwe endpoints for endpoint in new_endpoints - old_endpoints: changes.append(f"✅ NIEUW: {endpoint} toegevoegd") # Verwijderde endpoints for endpoint in old_endpoints - new_endpoints: changes.append(f"❌ VERWIJDERD: {endpoint} verwijderd") return changes # Voorbeeld gebruik with open('openapi-old.json') as f: old_spec = json.load(f) with open('openapi-new.json') as f: new_spec = json.load(f) changelog = generate_changelog(old_spec, new_spec) print("\n".join(changelog)) ``` ### 6.2 Dynamische Voorbeeld Generatie ```javascript // example-generator.js function generateExamples(openapiSpec) { const examples = {}; Object.entries(openapiSpec.paths).forEach(([path, methods]) => { Object.entries(methods).forEach(([method, operation]) => { const example = { request: { method: method.toUpperCase(), url: `https://api.example.com${path}`, headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer {token}' } }, response: { status: 200, body: generateExampleBody(operation.responses['200']) } }; examples[`${method}${path}`] = example; }); }); return examples; } function generateExampleBody(responseSchema) { // Implementeer logica om voorbeeld data te genereren // op basis van het response schema return { "id": 1, "name": "voorbeeld" }; } ``` ## 7. Monitoring en Onderhoud ### 7.1 Documentatie Health Check ```yaml # health-check.yaml apiVersion: batch/v1 kind: CronJob metadata: name: docs-health-check spec: schedule: "0 8 * * 1" # Elke maandag om 08:00 jobTemplate: spec: template: spec: containers: - name: health-check image: curlimages/curl:latest command: - /bin/sh - -c - | curl -f https://docs.example.com/ || exit 1 curl -f https://docs.example.com/openapi.json || exit 1 restartPolicy: OnFailure ``` ### 7.2 Usage Analytics ```html <!-- Tracking script voor documentatie gebruik --> <script> // Plaats in documentatie HTML fetch('https://analytics.example.com/track', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ page: window.location.pathname, timestamp: new Date().toISOString(), userAgent: navigator.userAgent }) }); </script> ``` ## 8. Best Practices en Tips 1. **Annotatie Consistentie**: Gebruik consistente annotaties doorheen de codebase 2. **Validatie in CI**: Voer OpenAPI validatie uit in elke build 3. **Versionering**: Houd API versies bij in de documentatie 4. **Review Process**: Implementeer documentatie review in pull requests 5. **Monitoring**: Monitor documentatie beschikbaarheid en performance ## 9. Troubleshooting ### Veelvoorkomende Problemen 1. **Ontbrekende annotaties**: Zorg dat alle endpoints geannoteerd zijn 2. **Validatiefouten**: Gebruik de OpenAPI validator voor debugging 3. **Build failures**: Check dependencies en plugin configuraties 4. **Hosting issues**: Verifieer CORS instellingen en permissions Deze handleiding biedt een complete basis voor het automatiseren van REST API documentatie. Pas de tools en workflows aan naar de specifieke behoeften van jouw project en team.