mirror of
https://github.com/testthedocs/awesome-docs.git
synced 2026-07-19 07:42:19 -05:00
d2eb3c152e
Move topic pages to section index routes, standardize card-based content presentation, and simplify metadata typing while improving local search indexing for EnhancedLink entries. Refresh theme styling and replace unstable external links to keep metadata builds reliable.
61 lines
3.3 KiB
Markdown
61 lines
3.3 KiB
Markdown
# API Documentation
|
|
|
|
Tools and resources for creating, testing, and maintaining API documentation.
|
|
|
|
## Documentation Generators
|
|
|
|
### Interactive Documentation
|
|
<ResourceGrid>
|
|
<EnhancedLink url="https://swagger.io/" title="Swagger" description="Industry standard tooling for API design and documentation." />
|
|
<EnhancedLink url="https://redocly.github.io/redoc/" title="ReDoc" description="Clean, readable API docs generated from OpenAPI." />
|
|
<EnhancedLink url="https://mrin9.github.io/RapiDoc/index.html" title="RapiDoc" description="Web component for interactive OpenAPI documentation." />
|
|
<EnhancedLink url="https://bump.sh/" title="Bump.sh" description="Hosted API documentation platform with automated updates." />
|
|
</ResourceGrid>
|
|
|
|
### API Design Tools
|
|
<ResourceGrid>
|
|
<EnhancedLink url="https://stoplight.io/studio/" title="Stoplight Studio" description="Visual API design and OpenAPI editing environment." />
|
|
<EnhancedLink url="https://www.getpostman.com/" title="Postman" description="API development, testing, and collaboration platform." />
|
|
<EnhancedLink url="https://github.com/hoppscotch/hoppscotch" title="Hoppscotch" description="Open source API development and request testing tool." />
|
|
</ResourceGrid>
|
|
|
|
## Testing & Validation
|
|
|
|
### Linting & Quality
|
|
<ResourceGrid>
|
|
<EnhancedLink url="https://stoplight.io/open-source/spectral/" title="Spectral" description="JSON and YAML linter with OpenAPI-focused rulesets." />
|
|
<EnhancedLink url="https://github.com/Redocly/openapi-cli" title="OpenAPI 3 CLI" description="CLI tooling for OpenAPI validation, linting, and bundling." />
|
|
<EnhancedLink url="https://github.com/wework/speccy" title="Speccy" description="OpenAPI specification linting and validation toolkit." />
|
|
</ResourceGrid>
|
|
|
|
### API Testing
|
|
<ResourceGrid>
|
|
<EnhancedLink url="https://dredd.org/en/latest/" title="Dredd" description="Validate API descriptions against real backend behavior." />
|
|
<EnhancedLink url="https://rest.sh/#/" title="Restish" description="Command-line client for exploring and testing REST APIs." />
|
|
</ResourceGrid>
|
|
|
|
## 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
|
|
|
|
<ResourceGrid>
|
|
<EnhancedLink url="https://dret.github.io/guidelines/" title="API Guidelines" description="Curated index of API design guideline resources." />
|
|
<EnhancedLink url="https://opensource.zalando.com/restful-api-guidelines/#" title="Zalando RESTful API Guidelines" description="Comprehensive REST and event-driven API conventions." />
|
|
<EnhancedLink url="https://apihandyman.io/" title="API Handyman" description="Practical writing and API design guidance for teams." />
|
|
<EnhancedLink url="https://lornajane.net/posts/2023/tips-for-better-documentation-with-openapi" title="Tips for Better Documentation with OpenAPI" description="Actionable guidance for writing stronger OpenAPI docs." />
|
|
</ResourceGrid>
|