Template for API projects within

Git Workflow Guide for API Designers

Introduction

This guide provides an overview of the Git-based workflow specifically tailored for API designers working in Stoplight.

1. Setup and Initial Planning

• 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

2. Designing the API

• 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

3. Finalizing and Pushing Changes

• 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.

Conclusion

Following this workflow will help maintain a high standard of quality and consistency in your API projects.

Git Workflow Guide for Documentation Writers

Introduction

This guide focuses on the documentation process for teams using a Git-based workflow in a collaborative API development environment.

1. Understanding the API Design

• 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.

2. Collaborative Writing and Revisions

• 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.

3. Publishing and Maintenance

• 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.

Conclusion

Adhering to this workflow ensures your documentation is accurate, up-to-date, and synchronized with API development.