# API Documentation

Tools and resources for creating, testing, and maintaining API documentation.

## Documentation Generators

### Interactive Documentation
- [Swagger](https://swagger.io/) - Industry standard for API documentation
- [ReDoc](https://redocly.github.io/redoc/) - Beautiful API documentation from OpenAPI
- [RapiDoc](https://mrin9.github.io/RapiDoc/index.html) - Custom element for OpenAPI docs
- [Bump.sh](https://bump.sh/) - API documentation platform with automated updates

### API Design Tools
- [Stoplight Studio](https://stoplight.io/studio/) - Visual API design editor
- [Postman](https://www.getpostman.com/) - API development environment
- [Hoppscotch](https://github.com/hoppscotch/hoppscotch) - Open source API development

## Testing & Validation

### Linting & Quality
- [Spectral](https://stoplight.io/open-source/spectral/) - JSON/YAML linter with OpenAPI rules
- [OpenAPI 3 CLI](https://github.com/Redocly/openapi-cli) - Command line tools for OpenAPI
- [Speccy](https://github.com/wework/speccy) - OpenAPI specification linter

### API Testing
- [Optic](https://www.useoptic.com/) - API change detection and testing
- [Restish](https://rest.sh/#/) - CLI for interacting with REST APIs

## Best Practices

### Structure Your API Docs
1. **Overview** - What does your API do?
2. **Authentication** - How to authenticate requests
3. **Endpoints** - Available endpoints with examples
4. **Data Models** - Request/response schemas
5. **Error Handling** - Error codes and messages

### Tips for Better Documentation
- Use real examples in your API documentation
- Include interactive testing capabilities
- Document error scenarios thoroughly
- Provide code samples in multiple languages
- Keep documentation in sync with API changes

## Guidelines & Resources

- [API Guidelines](https://dret.github.io/guidelines/) - Collection of API design guidelines
- [Zalando RESTful API Guidelines](https://opensource.zalando.com/restful-api-guidelines/#) - Comprehensive REST API guidelines
- [API Handyman](https://apihandyman.io/) - API design and documentation blog
- [Tips for better documentation with OpenAPI](https://lornajane.net/posts/2023/tips-for-better-documentation-with-openapi)