Skip to content

Codex: Improve docs for newcomers #799

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
f3l1x wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Codex: Improve docs for newcomers #799

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
178 changes: 54 additions & 124 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,164 +24,94 @@ Website 🚀 <a href="https://contributte.org">contributte.org</a> | Contact

-----

## Goal
## What is this project?

Main goal is to provide best prepared API starter-kit project for Nette-Apitte developers.
Apitte Skeleton is a batteries-included starter kit for building REST APIs on top of Nette 3 and [contributte/apitte](https://contributte.org/packages/contributte/apitte.html). It ships with Doctrine ORM, sensible defaults, and developer tooling so you can focus on shipping features instead of wiring infrastructure.

Focused on:
Key features:

- PHP 8.2+
- `nette/*` packages
- build PSR-7 API via `contributte/apitte`
- Doctrine ORM via `nettrine/*`
- Symfony components via `contributte/*`
- codestyle checking via **CodeSniffer** and `contributte/qa`
- static analysing via **phpstan** and `contributte/phpstan`
- unit / integration tests via **Nette Tester** and `contributte/tester`

You can try it out yourself either by running it with docker, or more easily with docker-compose.

## Demo

https://examples.contributte.org/apitte-skeleton/

## Install with [docker](https://github.com/docker/docker/)
- PHP 8.2+ with Nette 3 and Contributte integrations
- PSR-7 API stack via Apitte
- Doctrine ORM with migrations and fixtures
- Symfony Serializer/Validator support
- QA tools preconfigured (CodeSniffer, PHPStan, Nette Tester)

1) At first, use composer to install this project.
Explore the live demo: https://examples.contributte.org/apitte-skeleton/
Copy link

@coderabbitai coderabbitai bot Nov 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Wrap bare URL in markdown link syntax.

Line 39 contains a bare URL. For consistent markdown formatting and to enable clickable links in rendered documentation, wrap it in link syntax.

-Explore the live demo: https://examples.contributte.org/apitte-skeleton/
+Explore the live demo: [https://examples.contributte.org/apitte-skeleton/](https://examples.contributte.org/apitte-skeleton/)
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)

39-39: Bare URL used

(MD034, no-bare-urls)

🤖 Prompt for AI Agents 
In README.md around line 39, the bare URL
"https://examples.contributte.org/apitte-skeleton/" should be wrapped in
Markdown link syntax; edit that line to replace the raw URL with a Markdown link
(e.g. [text](https://examples.contributte.org/apitte-skeleton/)) using an
appropriate link label so the URL becomes clickable and consistent with the rest
of the document.


```bash
composer create-project -s dev contributte/apitte-skeleton
```
## Quick start

2) After that, you have to setup database.
If you want the fastest way to try the API locally, use Docker Compose:

1. Setup PostgreSQL 10. You can start it manually or use docker image `dockette/postgres:15`.
```bash
composer create-project -s dev contributte/apitte-skeleton
cd apitte-skeleton
cp config/local.neon.dist config/local.neon # adjust DB credentials if needed
docker-compose up
```

```bash
docker run -it -p 5432:5432 -e POSTGRES_PASSWORD=contributte -e POSTGRES_USER=contributte dockette/postgres:15
```
Once the containers are up, open http://localhost:8000 and browse the sample endpoints:
Copy link

@coderabbitai coderabbitai bot Nov 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Wrap bare URL in markdown link syntax.

Line 52 contains a bare URL. For consistent markdown formatting and clickable links in rendered documentation, wrap it in link syntax.

-Once the containers are up, open http://localhost:8000 and browse the sample endpoints:
+Once the containers are up, open [http://localhost:8000](http://localhost:8000) and browse the sample endpoints:
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
Once the containers are up, open http://localhost:8000 and browse the sample endpoints:
Once the containers are up, open [http://localhost:8000](http://localhost:8000) and browse the sample endpoints:
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)

52-52: Bare URL used

(MD034, no-bare-urls)

🤖 Prompt for AI Agents 
In README.md around line 52, the sentence contains a bare URL; replace it with a
Markdown link by wrapping the URL in Markdown link syntax so it becomes a
clickable link (use the URL as link text and target or provide descriptive text
pointing to the same URL) to ensure consistent formatting in rendered docs.


Or use make task, `make docker-postgres`.
- [GET] `/api/public/v1/openapi/meta` – OpenAPI JSON
- [GET] `/api/v1/users` – list users
- [POST] `/api/v1/users/create` – create a user

2. Setup MariaDB 10.4. You can start it manually or use docker image `mariadb:10.4`.
## Manual setup (no Docker)

```bash
docker run -it -d -p 3306:3306 -e MARIADB_ROOT_PASSWORD=contributte -e MARIADB_PASSWORD=contributte -e MARIADB_USER=contributte -e MARIADB_DATABASE=contributte mariadb:10.4
```
1. Install the project:

Or use make task, `make docker-mariadb`.
```bash
composer create-project -s dev contributte/apitte-skeleton
cd apitte-skeleton
```

3) Custom configuration file is located at `config/local.neon`. Edit it if you want.
2. Configure your database by copying the template and setting connection details (PostgreSQL or MariaDB):

Default configuration should look like this. Pick PostgreSQL or MariaDB.
```bash
cp config/local.neon.dist config/local.neon
```

```neon
# Host Config
parameters:

# Database
database:

# Postgres
driver: pdo_pgsql
host: database
dbname: contributte
user: contributte
password: contributte
port: 5432

# MariaDB
driver: pdo_mysql
host: database
driver: pdo_pgsql # or pdo_mysql
host: 127.0.0.1
dbname: contributte
user: contributte
password: contributte
port: 3306
port: 5432 # or 3306 for MariaDB
```

4) Ok database is now running and application is configured to connect to it. Let's create initial data.

Run `NETTE_DEBUG=1 bin/console migrations:migrate` to create tables.
Run `NETTE_DEBUG=1 bin/console doctrine:fixtures:load --append` to create first user(s).

Or via task `make build`.

5) Start your devstack or use PHP local development server.

You can start PHP server by running `php -S localhost:8000 -t www` or use prepared make task `make dev`.
3. Start your database (examples):

6) Open http://localhost and enjoy!

Take a look at:
- [GET] http://localhost:8000/api/public/v1/openapi/meta (Swagger format)
- [GET] http://localhost:8000/api/v1/users
- [GET] http://localhost:8000/api/v1/users?_access_token=admin
- [GET] http://localhost:8000/api/v1/users/1?_access_token=admin
- [GET] http://localhost:8000/api/v1/users/999?_access_token=admin
- [GET] http://localhost:8000/api/v1/users/email?email=admin@admin.cz&_access_token=admin
- [GET] http://localhost:8000/api/v1/static/text
- [POST] http://localhost:8000/api/v1/users/create

## Install with [docker compose](https://github.com/docker/compose)

1) At first, use composer to install this project.

```
composer create-project -s dev contributte/apitte-skeleton
```bash
docker run -p 5432:5432 -e POSTGRES_PASSWORD=contributte -e POSTGRES_USER=contributte dockette/postgres:15
# or
docker run -p 3306:3306 -e MARIADB_ROOT_PASSWORD=contributte -e MARIADB_USER=contributte -e MARIADB_PASSWORD=contributte -e MARIADB_DATABASE=contributte mariadb:10.4
```
Comment on lines +87 to 90
Copy link

@coderabbitai coderabbitai bot Nov 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Add language identifier to code block.

Line 87–90 contains a fenced code block without a language specifier. Add bash to enable syntax highlighting in rendered documentation.

-   ```
+   ```bash
    docker run -p 5432:5432 -e POSTGRES_PASSWORD=contributte -e POSTGRES_USER=contributte dockette/postgres:15
    # or
    docker run -p 3306:3306 -e MARIADB_ROOT_PASSWORD=contributte -e MARIADB_USER=contributte -e MARIADB_PASSWORD=contributte -e MARIADB_DATABASE=contributte mariadb:10.4
-   ```
+   ```
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)

90-90: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🤖 Prompt for AI Agents 
In README.md around lines 87 to 90, the fenced code block lacks a language
identifier; update the opening fence from ``` to ```bash so the block becomes
```bash and preserves the existing indented commands, ensuring syntax
highlighting is enabled in rendered docs.


2) Modify `config/local.neon` and set host to `postgres` or `mariadb`

Default configuration should look like this. There is preconfigured database. Pick PostgreSQL or MariaDB.

```neon
# Host Config
parameters:

# Database
database:

# Postgres
driver: pdo_pgsql
host: database
dbname: contributte
user: contributte
password: contributte
port: 5432
4. Prepare the schema and seed data:

# MariaDB
driver: pdo_mysql
host: database
dbname: contributte
user: contributte
password: contributte
port: 3306
```bash
NETTE_DEBUG=1 bin/console migrations:migrate
NETTE_DEBUG=1 bin/console doctrine:fixtures:load --append
```

3) Run `docker-compose up`
5. Run the development server:

4) Open http://localhost and enjoy!

Take a look at:
- [GET] http://localhost:8000/api/public/v1/openapi/meta (Swagger format)
- [GET] http://localhost:8000/api/v1/users
- [GET] http://localhost:8000/api/v1/users?_access_token=admin
- [GET] http://localhost:8000/api/v1/users/1?_access_token=admin
- [GET] http://localhost:8000/api/v1/users/999?_access_token=admin
- [GET] http://localhost:8000/api/v1/users/email?email=admin@admin.cz&_access_token=admin
- [POST] http://localhost:8000/api/v1/users/create
- [GET] http://localhost:8000/api/v1/static/text?_access_token=admin
- [GET] http://localhost:8000/api/v1/error/exception?_access_token=admin
```bash
make dev # or: php -S localhost:8000 -t www
```

## (Optional) REST API documentation
## Useful commands

Since we have OpenAPI specification available at `/api/public/v1/openapi/meta` you just need to add UI for it (e.g. to `www/doc` directory or as a standalone application).
- `make docker-postgres` / `make docker-mariadb` – start helper DB containers
- `make build` – run migrations, load fixtures, and warm up cache
- `make qa` – run static analysis and code style checks
- `make tests` – execute the test suite

Available options are:
## API discovery

- [Swagger UI](https://swagger.io/tools/swagger-ui/) + [themes](https://github.com/ostranme/swagger-ui-themes)
- [ReDoc](https://github.com/Redocly/redoc)
- other
OpenAPI metadata is available at `/api/public/v1/openapi/meta`, so you can plug in your favorite viewer (Swagger UI, ReDoc, etc.). The repository also includes `tests/cases/E2E/api.http` with ready-to-use HTTP requests for tools like PhpStorm.

## Features

Expand Down