Ontwikkel een PHP-script voor geautomatiseerde RESTful API-documentatie
description
Met deze prompt kun je efficiënt een PHP-oplossing bouwen die je API-documentatie automatisch bijwerkt en onderhoudt, waardoor tijd wordt bespaard en fouten worden verminderd. Dit is beter dan handmatige documentatie omdat het consistentie en actualiteit waarborgt.
prompt
Help me een PHP-script te ontwikkelen dat automatisch RESTful API-documentatie genereert op basis van mijn bestaande API-endpoints. Leg uit hoe ik de documentatie kan configureren en bijwe ...
try_prompt
generate_helper
disclaimerOnPageApi
tags
ai_answers
provider: openai
model: gpt-4.1-nano
Natuurlijk! Hier is een overzicht en een voorbeeld van hoe je een PHP-script kunt maken dat automatisch Swagger API-documentatie genereert en bijwerkt op basis van je bestaande API-endpoints.
### Stap 1: API-specificatie ophalen
Je kunt je bestaande Swagger JSON gebruiken als basis. Het script leest deze JSON en past het aan bij nieuwe of gewijzigde endpoints.
### Stap 2: Script om Swagger JSON te beheren
Hieronder een voorbeeld PHP-script dat je kunt gebruiken om je Swagger-documentatie te genereren en bij te werken:
```php
<?php
// URL van je bestaande Swagger API-specificatie
$swaggerUrl = 'https://mijnapi.com/swagger.json';
// Bestandslocatie waar de gegenereerde Swagger JSON wordt opgeslagen
$swaggerFile = __DIR__ . '/swagger_generated.json';
// Laad de bestaande Swagger-specificatie
$swaggerJson = file_get_contents($swaggerUrl);
if ($swaggerJson === false) {
die("Kon Swagger JSON niet ophalen.");
}
$swaggerData = json_decode($swaggerJson, true);
if ($swaggerData === null) {
die("Ongeldige JSON in Swagger-bestand.");
}
// Functie om nieuwe endpoints toe te voegen of bestaande bij te werken
function updateEndpoints(&$swaggerData) {
// Voorbeeld: Voeg een nieuw endpoint toe
$newPath = '/nieuw-endpoint';
$swaggerData['paths'][$newPath] = [
'get' => [
'summary' => 'Nieuw endpoint',
'responses' => [
'200' => [
'description' => 'Succesvolle reactie',
],
],
],
];
// Hier kun je logica toevoegen om je API automatisch te scannen of te genereren
// Bijvoorbeeld door je codebase te parsen of door handmatig alle endpoints toe te voegen
}
// Voer de update uit
updateEndpoints($swaggerData);
// Sla de bijgewerkte Swagger JSON op
file_put_contents($swaggerFile, json_encode($swaggerData, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES));
echo "Swagger-documentatie is bijgewerkt en opgeslagen.";
?>
```
### Stap 3: Documentatie bijwerken bij API-uitbreiding
- Pas de `updateEndpoints()` functie aan zodat deze automatisch alle nieuwe API-endpoints toevoegt of bijwerkt.
- Dit kan door bijvoorbeeld je API routes te scannen of door je endpoints te documenteren in een aparte structuur die je script leest.
- Automatiseer het proces door dit script te laten draaien na elke API-uitbreiding, bijvoorbeeld via een CI/CD pipeline.
### Stap 4: Documentatie hosten
- Plaats de gegenereerde `swagger_generated.json` op je server.
- Gebruik Swagger UI of een vergelijkbare tool om je API-documentatie visueel te maken:
```html
<!DOCTYPE html>
<html>
<head>
<title>API Documentatie</title>
<link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/swagger-ui-dist/swagger-ui.css" />
</head>
<body>
<div id="swagger-ui"></div>
<script src="https://cdn.jsdelivr.net/npm/swagger-ui-dist/swagger-ui-bundle.js"></script>
<script>
const ui = SwaggerUIBundle({
url: "/pad/naar/swagger_generated.json",
dom_id: '#swagger-ui',
});
</script>
</body>
</html>
```
### Samenvatting
- Laad je bestaande Swagger JSON.
- Voeg nieuwe endpoints toe of werk bestaande bij via je PHP-script.
- Sla de JSON op en host je API-documentatie met Swagger UI.
- Automatiseer het proces bij uitbreiding van je API voor consistente en actuele documentatie.
Als je verdere hulp nodig hebt bij het automatiseren van endpoint detectie of integratie, vraag gerust!
provider: deepseek
model: deepseek-chat
Ik help je graag een PHP-script te ontwikkelen voor automatische Swagger-documentatie. Hier is een complete oplossing:
## 1. Installatievereisten
```bash
composer require zircote/swagger-php
```
## 2. Basis PHP-Script
```php
<?php
require_once 'vendor/autoload.php';
use OpenApi\Generator;
class SwaggerDocumentatieGenerator {
private $apiSpecUrl;
private $outputPath;
public function __construct($apiSpecUrl, $outputPath = 'swagger.json') {
$this->apiSpecUrl = $apiSpecUrl;
$this->outputPath = $outputPath;
}
public function genereerDocumentatie() {
try {
// Haal bestaande API-specificatie op
$bestaandeSpec = file_get_contents($this->apiSpecUrl);
$bestaandeData = json_decode($bestaandeSpec, true);
// Genereer nieuwe documentatie op basis van code-annotaties
$openapi = Generator::scan(['./src', './api']); // Pas paden aan naar jouw structuur
$nieuweData = json_decode($openapi->toJson(), true);
// Merge bestaande en nieuwe data
$samengevoegdeData = array_merge($bestaandeData, $nieuweData);
// Sla op
file_put_contents($this->outputPath, json_encode($samengevoegdeData, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES));
return "Documentatie succesvol gegenereerd en opgeslagen in " . $this->outputPath;
} catch (Exception $e) {
return "Fout bij genereren documentatie: " . $e->getMessage();
}
}
}
// Gebruik
$generator = new SwaggerDocumentatieGenerator('https://mijnapi.com/swagger.json');
echo $generator->genereerDocumentatie();
?>
```
## 3. Annotatie-voorbeelden voor je endpoints
```php
<?php
/**
* @OA\Info(
* title="Mijn API",
* version="1.0.0",
* description="Documentatie voor mijn RESTful API"
* )
*/
/**
* @OA\Get(
* path="/api/users",
* summary="Haal alle gebruikers op",
* tags={"Gebruikers"},
* @OA\Response(
* response=200,
* description="Lijst van gebruikers",
* @OA\JsonContent(
* type="array",
* @OA\Items(ref="#/components/schemas/User")
* )
* )
* )
*/
class UserController {
// Je controller code hier
}
/**
* @OA\Schema(
* schema="User",
* @OA\Property(property="id", type="integer", example=1),
* @OA\Property(property="name", type="string", example="Jan Jansen"),
* @OA\Property(property="email", type="string", format="email", example="jan@voorbeeld.nl")
* )
*/
class User {
// Je model code hier
}
?>
```
## 4. Automatisering met Composer Script
Voeg toe aan je `composer.json`:
```json
{
"scripts": {
"generate-docs": "php generate-swagger.php",
"update-docs": "php update-swagger.php"
}
}
```
## 5. Update Script voor API-uitbreidingen
```php
<?php
// update-swagger.php
require_once 'vendor/autoload.php';
use OpenApi\Generator;
// Scan alle relevante mappen voor nieuwe annotaties
$openapi = Generator::scan(['./src', './api', './controllers']);
// Bestaande documentatie ophalen en mergen
$bestaande = json_decode(file_get_contents('https://mijnapi.com/swagger.json'), true);
$nieuwe = json_decode($openapi->toJson(), true);
$bijgewerkt = array_merge_recursive($bestaande, $nieuwe);
// Opslaan
file_put_contents('swagger.json', json_encode($bijgewerkt, JSON_PRETTY_PRINT));
echo "Documentatie bijgewerkt!\n";
?>
```
## 6. Configuratiebestand
Maak een `swagger-config.php`:
```php
<?php
return [
'scan_directories' => [
'./src',
'./api',
'./controllers'
],
'output_file' => 'swagger.json',
'base_url' => 'https://mijnapi.com',
'exclude' => [
'./vendor',
'./tests'
]
];
?>
```
## 7. Gebruiksaanwijzing
1. **Installatie**: `composer require zircote/swagger-php`
2. **Annoteer endpoints**: Voeg Swagger annotaties toe aan je code
3. **Genereer**: `php generate-swagger.php` of `composer run generate-docs`
4. **Bijwerken**: Bij nieuwe endpoints: `composer run update-docs`
## 8. CI/CD Integratie
Voeg toe aan je deployment pipeline:
```yaml
- name: Genereer Swagger docs
run: composer run generate-docs
- name: Deploy documentatie
run: scp swagger.json server:/path/to/docs/
```
De documentatie wordt automatisch bijgewerkt wanneer je nieuwe endpoints toevoegt met de juiste annotaties!