APPNETOS is under active development This website and its documentation are being prepared for public launch. Content and features may change.
Select Theme
Loading

Swagger UI

Explore, understand and test APPNETOS REST APIs interactively.

appnetos-api-dev provides a developer-facing Swagger UI for OpenAPI definitions generated from APPNETOS REST Collections. It helps developers inspect available operations, understand request and response schemas and send test requests to the target application.

How the pieces fit together

Swagger UI is a consumer of the generated OpenAPI contract, not the component that discovers REST Collections or implements endpoints. The generator builds a context-specific definition; the developer application presents it; the browser sends requests to the target REST application.

REST Collections are documented by the OpenAPI generator; appnetos-api-dev loads the generated definition in Swagger UI, which sends test requests to the target REST API.
Generated documentation and live REST execution remain separate responsibilities.

The appnetos-api-dev application

appnetos-api-dev is a dedicated APPNETOS application for browsing generated API definitions and testing endpoints. Its developer interface is separate from the application that actually serves the REST resource.

Definitions are generated per application and REST context. For example, rest and admin-rest have independent contracts, routes and security requirements. Select the definition matching the API you intend to test.

Generate and discover definitions

Before opening Swagger UI, generate the OpenAPI files for the target application and context. From the APPNETOS project root:

php bin/appnetos cmd appnetos:openapi:generate my-application
php bin/appnetos cmd appnetos:openapi:generate my-application admin-rest

The generator writes a definition and metadata under the application-specific output directory:

custom/<application>/.files/OpenAPI/<context>/
├── rest.json
└── metadata.json

Open the developer application and select the generated definition. If a definition is missing, confirm that generation completed successfully, the requested REST context exists and the files are accessible to the developer application.

Inspect an endpoint

Swagger UI groups the operations described by the selected OpenAPI definition. Expand an operation to inspect its HTTP method, route, parameters, request body, possible responses and associated Document schemas. The displayed contract reflects the last successful generation, not necessarily every subsequent source-code change.

Element What to check
Server The host and context route of the REST application you want to call.
Operation HTTP method and resource path exposed by the annotated REST Collection.
Parameters Required path or query values and their documented types.
Request body Expected JSON structure and documented property constraints.
Responses Documented status codes and response schemas.

Send a test request

  1. Select the appropriate application/context definition and verify the server URL.
  2. Expand the desired REST operation and select Try it out.
  3. Provide required parameters or a JSON request body.
  4. Configure authorization when the endpoint requires it.
  5. Select Execute and inspect the request URL, status code, response headers and response body.

Use a development or staging target for write operations. POST, PUT, PATCH and DELETE may modify persistent data; Swagger UI does not simulate them.

Authentication and CORS

Depending on the target application's context-specific security configuration, a REST endpoint may require Basic Authentication or a Bearer token. Use Swagger UI's Authorize feature when the generated definition advertises a supported security scheme.

When the developer application and target API use different origins, the browser enforces CORS. The target application's REST context must allow the developer application's origin and any required methods and headers. For authorized requests, verify that the necessary authorization header is permitted. Browser preflight failures occur before the intended REST operation is executed.

Authentication and CORS solve different problems: valid credentials do not override a browser CORS rejection, and an allowed origin does not grant access to a protected endpoint.

Troubleshooting

Symptom Recommended check
Definition not listed Generate the correct application/context and check the resulting rest.json and metadata.json.
Endpoint missing or outdated Check the REST Collection annotation and regenerate the OpenAPI definition.
Unexpected target host Review application routes and the generated OpenAPI servers entries.
401 or 403 Verify credentials, the configured authentication scheme and REST authorization requirements.
CORS / preflight error Check the target REST context's allowed origins, methods and headers; inspect browser network diagnostics.
400 / validation failure Compare submitted parameters and JSON values against the documented schema and server response.
404 Confirm the application host, context slug, resource slug and HTTP method.

Public API Methods

Swagger UI is an interactive developer interface, not an additional public PHP Core API. The REST and OpenAPI services it uses are documented in REST Collections and OpenAPI Generator. Application-specific UI controller methods are intentionally not listed here without their source implementation.

Next Steps

Previous

OpenAPI Generator

Explore OpenAPI Generator

Next

Commands & Workers

Explore Commands & Workers