This guide provides an overview of the Git-based workflow specifically tailored for API designers working in Stoplight.
- Create a Copy of thie Repot: Copy this repo and import into your Stoplight Workspace.
- Gather Requirements: Compile all necessary API requirements including user stories and data models and create a markdown document for it.
- Create a First Commit: Push the first commit to VCS Provider
- Create a draft pull request
- OpenAPI Specification: Use Stoplight Studio to create or edit your OpenAPI specs.
- Reusable Components: Focus on using reusable components to ensure consistency across your API designs.
- Linting Errors: Make sure to fix linting issues within Stoplight
- Final Review and Merge: Conduct a final review with all stakeholders before merging changes to the main branch.
- Continual Updates: Regularly update your API specs to reflect any changes in requirements or functionality.
Following this workflow will help maintain a high standard of quality and consistency in your API projects.
This guide focuses on the documentation process for teams using a Git-based workflow in a collaborative API development environment.
- Review API Specifications: Begin by thoroughly reviewing the OpenAPI documents to understand the API functionality.
- Initial Documentation Draft: Draft the initial versions of your API documentation based on your understanding.
- Git Branches for Documentation: Utilize separate Git branches to manage different documentation drafts.
- Pull Requests for Reviews: Use pull requests to facilitate reviews of the documentation, allowing for feedback and revisions.
- Final Review and Merge: Ensure the documentation accurately reflects the API and meets quality standards before merging.
- Update and Iterate: Continuously update the documentation to incorporate changes in the API and user feedback.
Adhering to this workflow ensures your documentation is accurate, up-to-date, and synchronized with API development.