mirror of
https://github.com/testthedocs/awesome-docs.git
synced 2026-07-20 07:54:11 -05:00
sven
edbcb85587
- Restructured homepage with clear category overview - Created comprehensive Site Generators page with detailed tool descriptions - Built API Documentation page covering tools, testing, and best practices - Added Quality Assurance page with linting, testing, and accessibility tools - Updated navigation with organized tool categories and resources - Enhanced sidebar with logical content grouping - Transformed flat README list into searchable, navigable documentation New structure: - Core Tools: Site Generators, API Documentation - Content & Quality: Writing Tools, Quality Assurance - Resources: Style Guides, Reading List, GitHub Actions - Getting Started: Introduction, Installation All content now properly categorized and easily discoverable through navigation and search.
50 lines
2.2 KiB
Markdown
50 lines
2.2 KiB
Markdown
# 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) |