Let me give you an example of an ideal Stoplight workflow that some users use.
- A user creates an API design using Stoplight’s modeling tools for OpenAPI Specification.
- The user then shares the auto-generated documentation from the design with their team, do some mocking to see how it would behave in real life, and maybe make a few improvements.
- The user implements that design in their API in an internal git repo (might be pushed to GitHub, GitLab, etc).
- The user might then return to Stoplight to use some of the contract testing tools to make sure the API implementation matches the design they created on Stoplight. Basically, anything they need to do to get it ready for production.
Now if they have an existing specification in an existing git repo (might be on GitHub, GitLab, etc), step 1 would change. They would probably take the file from the repo and then use the import file feature in Stoplight to upload the specification to work on it in Stoplight.
I know that was a really longwinded response. But hopefully, it gives you an idea how Stoplight works right now.
This isn’t to say it is how it will always work. We are constantly building new features to support new workflows and support API providers. We’ve definitely heard from users that they would like their specification to live in the same repo as their implementation. We are working towards a solution for this.
For the purpose of this thread, I think it might be helpful to separate the idea of the API implementation and the API specification (or design). Right now, the file you import could be from a locally cloned git repo but there is not a two way connection from Stoplight to your local repo (yet).
This is a feature request that we are exploring in the future.
Stoplight users use the platform as a centralized location to keep their API designs, mock servers, contract tests, and documentation. The implementation of the API lives a separate location, not within the Stoplight project (or repo).