Help mij bij het implementeren van geavanceerde API-documentatie in CodeIgniter
description
Met deze prompt kan ik gedetailleerde en gestructureerde API-documentatie maken die mijn CodeIgniter-project beter toegankelijk maakt voor andere ontwikkelaars. Dit vermindert misverstanden en versnelt integraties, wat efficiënter is dan losse of handmatige documentatie. Door het gebruik van tools als Swagger kan ik mijn documentatie automatisch up-to-date houden en eenvoudig delen.
prompt
Help mij bij het ontwerpen en implementeren van uitgebreide API-documentatie voor mijn CodeIgniter-project. Beschrijf hoe ik documentatie kan genereren en onderhouden met tools zoals Swagger of ApiGen, inclusief voorbeelden van ...
try_prompt
generate_helper
disclaimerOnPageApi
tags
ai_answers
provider: openai
model: gpt-4.1-nano
Natuurlijk! Hier is een uitgebreide gids om API-documentatie voor je CodeIgniter 3.1.11-project te ontwerpen en te onderhouden met tools zoals Swagger en ApiGen.
---
## 1. API-documentatie met Swagger
### Voordelen
- Moderne, interactieve API-documentatie.
- Automatische generaties gebaseerd op OpenAPI-specificaties.
- Ondersteunt annotaties en configuratie via YAML/JSON.
### Stap 1: Schema en annotaties voorbereiden
Omdat CodeIgniter 3.1.11 geen ingebouwde ondersteuning voor Swagger-annotaties heeft, moet je handmatig een OpenAPI-specificatie (YAML of JSON) maken of genereren.
#### Voorbeeld van een basis OpenAPI YAML:
```yaml
openapi: 3.0.0
info:
title: Productcatalogus API
version: 1.0.0
paths:
/products:
get:
summary: "Lijst van producten"
responses:
'200':
description: "Succes"
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Product'
components:
schemas:
Product:
type: object
properties:
id:
type: integer
name:
type: string
price:
type: number
```
### Stap 2: API-specificaties handmatig maken
- Maak voor elke endpoint een entry in de YAML.
- Voeg parameters, responses en schemas toe.
### Stap 3: Een Swagger UI hosten
- Download de [Swagger UI](https://swagger.io/tools/swagger-ui/).
- Plaats de bestanden op je server.
- Koppel je YAML-bestand via de `swagger-initializer.js` of via URL.
**Voorbeeld:**
```html
<!DOCTYPE html>
<html lang="nl">
<head>
<meta charset="UTF-8" />
<title>API Documentatie</title>
<link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist/swagger-ui.css" />
</head>
<body>
<div id="swagger-ui"></div>
<script src="https://unpkg.com/swagger-ui-dist/swagger-ui-bundle.js"></script>
<script>
const ui = SwaggerUIBundle({
url: "/path/naar/openapi.yaml",
dom_id: '#swagger-ui',
});
</script>
</body>
</html>
```
---
## 2. API-documentatie met ApiGen
### Voordelen
- API-documentatie gebaseerd op PHP-doc-blokken.
- Geschikt voor REST API’s die niet per se Swagger gebruiken.
### Stap 1: ApiGen installeren
- Download ApiGen via [https://github.com/ApiGen/ApiGen](https://github.com/ApiGen/ApiGen).
- Plaats het in je project of gebruik Composer.
### Stap 2: Annotaties toevoegen in je CodeIgniter controllers
Gebruik PHPDoc-annotaties voor je API-methoden:
```php
/**
* @api {get} /products Lijst van producten
* @apiName GetProducts
* @apiGroup Product
*
* @apiSuccess {Object[]} products Lijst van producten.
* @apiSuccess {Number} products.id Product ID.
* @apiSuccess {String} products.name Naam van het product.
* @apiSuccess {Number} products.price Prijs van het product.
*/
public function products()
{
// je code
}
```
### Stap 3: ApiGen genereren
- Voer het commando uit:
```bash
apigen generate -s application/controllers -d docs/api
```
- De documentatie wordt gegenereerd in de map `docs/api`.
### Stap 4: Onderhoud
- Voeg telkens nieuwe annotaties toe bij het ontwikkelen.
- Herhaal het genereren-commando om je documentatie bij te werken.
---
## 3. Aanvullende tips
- **Gebruik consistente annotaties**: Zorg dat je voor elke API-methode duidelijke en consistente annotaties gebruikt.
- **Versiebeheer**: Onderhoud versies in je documentatie, vooral bij API-updates.
- **Automatiseer het proces**: Maak scripts of gebruik CI/CD om documentatie te genereren bij elke deployment.
- **Documenteer alle belangrijke endpoints**: Productcatalogus, winkelwagen en betalingen.
---
## Samenvatting
- **Swagger**: Handmatige YAML-configuratie en hosting via Swagger UI voor interactieve documentatie.
- **ApiGen**: PHP-docblokken in je controllers en automatische generatie van statische documentatie.
Wil je dat ik specifieke voorbeelden van annotaties voor jouw API geef of hulp bij het opzetten van een van deze tools?
provider: deepseek
model: deepseek-chat
Ik help je graag met het opzetten van uitgebreide API-documentatie voor je CodeIgniter 3.1.11 project. Hier is een complete handleiding:
## 1. Swagger/OpenAPI Implementatie
### Installatie
```bash
# Installeer composer packages
composer require zircote/swagger-php
composer require darkaonline/l5-swagger
```
### Configuratie in CodeIgniter
**application/config/swagger.php**
```php
<?php
defined('BASEPATH') OR exit('No direct script access allowed');
$config['swagger'] = array(
'api_base_path' => base_url(),
'swagger_ui_path' => 'api-docs',
'api_version' => '1.0.0',
'title' => 'Product Catalog API',
'description' => 'API voor productcatalogus, winkelwagen en betalingen',
'contact_email' => 'support@jouwdomein.nl',
'license' => 'MIT',
'license_url' => 'https://opensource.org/licenses/MIT'
);
```
### Voorbeeld Controller met Annotaties
**application/controllers/api/Products.php**
```php
<?php
defined('BASEPATH') OR exit('No direct script access allowed');
/**
* @OA\Info(
* title="Product Catalog API",
* version="1.0.0",
* description="API voor productbeheer, winkelwagen en betalingen",
* @OA\Contact(
* email="support@jouwdomein.nl"
* )
* )
* @OA\Server(
* url="http://localhost/your-project",
* description="Development Server"
* )
* @OA\Tag(
* name="Products",
* description="Product gerelateerde endpoints"
* )
*/
class Products extends CI_Controller {
public function __construct() {
parent::__construct();
$this->load->model('product_model');
}
/**
* @OA\Get(
* path="/api/products",
* tags={"Products"},
* summary="Haal alle producten op",
* description="Retourneert een lijst met alle beschikbare producten",
* @OA\Response(
* response=200,
* description="Succesvolle operatie",
* @OA\JsonContent(
* type="array",
* @OA\Items(ref="#/components/schemas/Product")
* )
* ),
* @OA\Response(
* response=500,
* description="Interne serverfout"
* )
* )
*/
public function index() {
$products = $this->product_model->get_all_products();
$this->output
->set_content_type('application/json')
->set_output(json_encode($products));
}
/**
* @OA\Get(
* path="/api/products/{id}",
* tags={"Products"},
* summary="Haal specifiek product op",
* description="Retourneert een specifiek product op basis van ID",
* @OA\Parameter(
* name="id",
* in="path",
* required=true,
* description="Product ID",
* @OA\Schema(type="integer")
* ),
* @OA\Response(
* response=200,
* description="Succesvolle operatie",
* @OA\JsonContent(ref="#/components/schemas/Product")
* ),
* @OA\Response(
* response=404,
* description="Product niet gevonden"
* )
* )
*/
public function get($id) {
$product = $this->product_model->get_product($id);
if ($product) {
$this->output
->set_content_type('application/json')
->set_output(json_encode($product));
} else {
$this->output
->set_status_header(404)
->set_output(json_encode(['error' => 'Product niet gevonden']));
}
}
/**
* @OA\Post(
* path="/api/products",
* tags={"Products"},
* summary="Maak nieuw product aan",
* description="Creëert een nieuw product in de catalogus",
* @OA\RequestBody(
* required=true,
* @OA\JsonContent(ref="#/components/schemas/ProductInput")
* ),
* @OA\Response(
* response=201,
* description="Product succesvol aangemaakt"
* ),
* @OA\Response(
* response=400,
* description="Ongeldige invoer"
* )
* )
*/
public function create() {
$data = json_decode($this->input->raw_input_stream, true);
// Validatie en opslag logica
}
}
/**
* @OA\Schema(
* schema="Product",
* type="object",
* title="Product",
* required={"id", "name", "price"},
* @OA\Property(
* property="id",
* type="integer",
* description="Unieke identifier van het product"
* ),
* @OA\Property(
* property="name",
* type="string",
* description="Naam van het product"
* ),
* @OA\Property(
* property="price",
* type="number",
* format="float",
* description="Prijs van het product"
* ),
* @OA\Property(
* property="description",
* type="string",
* description="Beschrijving van het product"
* ),
* @OA\Property(
* property="stock",
* type="integer",
* description="Aantal op voorraad"
* )
* )
*/
/**
* @OA\Schema(
* schema="ProductInput",
* type="object",
* required={"name", "price"},
* @OA\Property(property="name", type="string"),
* @OA\Property(property="price", type="number", format="float"),
* @OA\Property(property="description", type="string"),
* @OA\Property(property="stock", type="integer")
* )
*/
```
## 2. ApiGen Implementatie
### Installatie
```bash
composer require apigen/apigen
```
### Configuratie
**apigen.neon**
```yaml
destination: docs/api
source:
- application/controllers
- application/models
- application/libraries
exclude:
- application/cache
- application/logs
- application/third_party
title: "Product Catalog API Documentation"
templateTheme: "default"
```
### Voorbeeld Model Annotaties
**application/models/Cart_model.php**
```php
<?php
defined('BASEPATH') OR exit('No direct script access allowed');
/**
* Winkelwagen Model
*
* Beheert winkelwagenoperaties inclusief toevoegen, verwijderen en bijwerken
* van producten in de winkelwagen
*
* @package Models
* @subpackage Cart
* @category API Models
* @author Jouw Naam
* @version 1.0.0
*/
class Cart_model extends CI_Model {
/**
* Voeg product toe aan winkelwagen
*
* @param int $product_id ID van het product
* @param int $quantity Aantal stuks
* @param int $user_id Gebruikers ID (optioneel voor gastgebruikers)
* @return bool True bij succes, false bij fout
* @throws Exception Als product niet bestaat of niet op voorraad is
*/
public function add_to_cart($product_id, $quantity = 1, $user_id = null) {
// Implementatie logica
}
/**
* Haal winkelwagen inhoud op
*
* @param int $user_id Gebruikers ID of sessie ID voor gasten
* @return array Array met winkelwagen items
* @example
* <code>
* $cart = $this->cart_model->get_cart(123);
* </code>
*/
public function get_cart($user_id) {
// Implementatie logica
}
}
```
## 3. Documentatie Genereren
### Swagger Documentatie Genereren
```bash
# Genereer OpenAPI specificatie
./vendor/bin/openapi application/controllers -o public/swagger.json
# Of gebruik een controller methode
```
**application/controllers/Documentation.php**
```php
<?php
defined('BASEPATH') OR exit('No direct script access allowed');
class Documentation extends CI_Controller {
public function generate_swagger() {
$openapi = \OpenApi\Generator::scan(['application/controllers']);
header('Content-Type: application/json');
echo $openapi->toJson();
}
}
```
### ApiGen Documentatie Genereren
```bash
# Genereer documentatie
./vendor/bin/apigen generate
```
## 4. Router Configuratie
**application/config/routes.php**
```php
$route['api/products'] = 'api/products/index';
$route['api/products/(:num)'] = 'api/products/get/$1';
$route['api/cart'] = 'api/cart/index';
$route['api/cart/add'] = 'api/cart/add';
$route['api/payment/process'] = 'api/payment/process';
$route['api-docs'] = 'documentation/generate_swagger';
```
## 5. Onderhoud en Best Practices
1. **Consistente Annotaties**: Houd annotaties consistent across alle controllers
2. **Versionering**: Update API versie bij breaking changes
3. **Validatie**: Gebruik Swagger UI voor testen en validatie
4. **Automation**: Integreer documentatie generatie in deployment process
5. **Examples**: Voeg altijd voorbeelden toe aan complexe endpoints
## 6. Aanbevolen Structuur
```
application/
├── controllers/
│ ├── api/
│ │ ├── Products.php
│ │ ├── Cart.php
│ │ └── Payment.php
│ └── Documentation.php
├── models/
│ ├── Product_model.php
│ ├── Cart_model.php
│ └── Payment_model.php
└── config/
└── swagger.php
```
Deze setup geeft je een professionele API-documentatie die automatisch wordt bijgewerkt met je codewijzigingen. Swagger UI biedt een interactieve interface voor testen, terwijl ApiGen gedetailleerde code documentatie genereert.
error: Generation failed [deepseek] prompt_id=3897 locale=en err=DeepSeek connection/timeout