https://github.com/stoplightio/governance-template-repo
https://github.com/stoplightio/governance-template-repo
Last synced: 5 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/stoplightio/governance-template-repo
- Owner: stoplightio
- Created: 2024-05-29T10:22:38.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2025-04-23T14:27:00.000Z (about 1 year ago)
- Last Synced: 2026-01-15T20:25:10.197Z (5 months ago)
- Size: 6.84 KB
- Stars: 2
- Watchers: 3
- Forks: 2
- Open Issues: 2
-
Metadata Files:
- Readme: Readme.md
Awesome Lists containing this project
README
# 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.