Responses and OpenAPI Export
Document API responses with status codes and schemas. Export your API documentation to OpenAPI 3.1 format for use with other tools.
Complete API documentation includes response definitions for each endpoint. NeoArc supports a comprehensive set of HTTP status codes and exports to OpenAPI 3.1 format for compatibility with code generators, API gateways, and documentation tools.
Configuring Responses
Response Properties
HTTP Status Codes
NeoArc supports status codes across all standard categories:
2xx Success
| Status Code | Description |
|---|---|
| 200 OK | Standard success response |
| 201 Created | Resource created successfully |
| 202 Accepted | Request accepted for processing |
| 204 No Content | Success with no response body |
| 206 Partial Content | Range request successful |
3xx Redirection
| Status Code | Description |
|---|---|
| 301 Moved Permanently | Resource moved permanently |
| 302 Found | Temporary redirect |
| 304 Not Modified | Cached version is current |
| 307 Temporary Redirect | Temporary redirect (preserves method) |
| 308 Permanent Redirect | Permanent redirect (preserves method) |
4xx Client Errors
| Status Code | Description |
|---|---|
| 400 Bad Request | Malformed request |
| 401 Unauthorized | Authentication required |
| 403 Forbidden | Permission denied |
| 404 Not Found | Resource does not exist |
| 405 Method Not Allowed | HTTP method not supported |
| 409 Conflict | Request conflicts with current state |
| 422 Unprocessable Entity | Validation failed |
| 429 Too Many Requests | Rate limit exceeded |
5xx Server Errors
| Status Code | Description |
|---|---|
| 500 Internal Server Error | Unexpected server error |
| 501 Not Implemented | Feature not implemented |
| 502 Bad Gateway | Invalid upstream response |
| 503 Service Unavailable | Server temporarily unavailable |
| 504 Gateway Timeout | Upstream timeout |
Response Headers
Document response headers by linking to a header schema. Common response headers:
| Header | Purpose |
|---|---|
| X-Request-ID | Correlation identifier |
| X-RateLimit-Remaining | Rate limit information |
| ETag | Resource version for caching |
| Location | URI of created resource (201 responses) |
| Retry-After | When to retry (429, 503 responses) |
Common Response Patterns
Success with Data
200 OK with a schema defining the response body. Use for GET requests returning resources.
Created
201 Created with Location header pointing to the new resource. Use for POST requests that create resources.
No Content
204 No Content with no response body. Use for DELETE requests or updates that do not return data.
Error Response
Use a consistent error schema across all 4xx and 5xx responses. Include error code, message, and optional details.
OpenAPI Export
NeoArc exports API definitions to OpenAPI 3.1 format, compatible with:
API Gateways
Kong, AWS API Gateway
Code Generators
OpenAPI Generator, Swagger Codegen
Documentation Tools
Swagger UI, Redoc
Testing Tools
Postman, Insomnia
Mock Servers
Generate mock APIs for development
Export Mappings
NeoArc converts internal structures to OpenAPI format:
Type Specialisations in Export
Field type specialisations map to OpenAPI formats:
| Category | Formats |
|---|---|
| Date/Time | date-time, date, time |
| Strings | email, uri, uuid |
| Network | hostname, ipv4, ipv6 |
| Numbers | int32, int64, float, double |
| Binary | byte, binary, password |
Exporting Your API
Next Steps
Getting Started with REST APIs
Learn the fundamentals of authoring REST API documentation.
Learn more →