Cloning github repo

(Nicholaswade) #1

I’m a newbie to Spotlight, and I’ve stumbled at the first fence. I could link my Spotlight to my GitHub but when I came to import from my local repo I keep getting the introductory Spotlight material instead. After a LOT of clicking and reading it seems you need to go through a convoluted process involving generating a token and 2 user names - one for spotlight-username and the other for…???

git clone https://{stoplight-username}:$STOPLIGHT_TOKEN@git.stoplight.io/{username}/{project-name}.git

Also, I don’t see any path statement in there to access my local Git repo, so is it the main Git web repo?
The GitHub repo for my files has a path:
ozy1ozy/openapi-directory/APIs/apacta.com/0.0.2/swagger.yaml
but I can’t see that this is right?
What I did originally, was to copy an open source repo from GitHub to my GitHub and then download this repo to my local machine from which I thought I could then use Stoplight to access the local repo.
In all, I am totally confused…

(Taylor Barnett) #2

We don’t support direct GitHub import of your specification file (yet). I’m sorry if we made you think it was possible right now with the GitHub single sign on.

Stoplight is Git based in that your project is really a Git repository under the hood. So you can clone this repo and do whatever you want with it, push to another Git provider, make changes locally and push back to Stoplight, etc.

The docs you saw are for pulling your Stoplight project, but it sounds like you might have understood that now.

There is a structure for our projects (or repos under the hood), so you will need to get started with a new Stoplight project. The best way to get started would be to import your existing OAS file:

10%20AM
Screen Shot 2018-10-11 at 11.56.10 AM.png1622x452 16.5 KB

Let me know if you have anymore questions about this!

(Taylor Barnett) #3

2 user names - one for spotlight-username and the other for…???

And this looks like it was a typo, I’ll work on getting that fixed.

(Nicholaswade) #4

'fraid this just confuses the matter Taylor.
You say you don’t support direct GitHub (which is where my repo are based), so how am I supposed to access them?
All I can see is your Help file stating how to clone from Stoplight Git repo.
Are you are saying that whatever API you create and store in your own GitHub cannot then be imported into Stoplight Git repo and from the Stoplight Git repo into Stoplight in a new Stoplight project?
I get the feeling that users can only use Swagger or Stoplight to act as a repo for their files?

(Nicholaswade) #5

You could also do with mentioning that the user should go into Settings and use the project path name there. It seemed to change from what I called the project. i.e, Project_4 was changed to a path name of Project-4 (the example in the Help also calls for the project name instead of the project path name) and the file given the extension .git

NB: gradually losing the will to live…

(Taylor Barnett) #7

Let me give you an example of an ideal Stoplight workflow that some users use.

  1. A user creates an API design using Stoplight’s modeling tools for OpenAPI Specification.
  2. 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.
  3. The user implements that design in their API in an internal git repo (might be pushed to GitHub, GitLab, etc).
  4. 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).

(Nicholaswade) #8

Not wishing to sound difficult, but you just wrote:

“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.”

Which comes right back to my original question - How to get my repo from my GitHub into Stoplight? If I sound dumb I’m sorry, but something is simply not clicking for me. I’m sure your product is really nice to use once you get the hang of it.

(Taylor Barnett) #9

It’s not dumb! Talking about git can be confusing since many times git has sometimes become synonyms to GitHub, when GitHub is technically only a space you are hosting your repos. I only said “might be on GitHub, GitLab, etc” to illustrate this.

At this time, you cannot do this. You cannot import the whole API implementation of your API into Stoplight. Only the specification file.

Do you have your git repo from GitHub cloned locally? If so, can you find your OpenAPI Specification (fka Swagger) file? Once you’ve found it, you will upload that file to Stoplight using the feature I talked about in an earlier reply.

One other question: What are your goals for using Stoplight? This might help me support you better.

(Kmeister) #10

We’ve also stumbled on this one, as its not easy to manage between 2 repos especially when there are multiple changes in progress, which aren’t ready to publish yet.

The way we do that is to copy and paste the spec or design files into </> code view of the stoplight app. We then edit within stoplight (their interface is extremely good). We then copy and paste out of the app into our git repo when we’re ready to commit that feature. In our build process we use their prism tool to test the api before deploying.

(Taylor Barnett) #11

@kmeister You’ll like some of the new feature ideas we are working on. We do want to make this easier. I’ll send you some questions soon about your desired workflow.

(Nicholaswade) #12

Yep, thanks for confirmation. That’s what I ended up doing, but I’m not happy about it. Kind of ‘clutzy’ (I think). GitHub is a pretty reasonable repository and with Git, it keeps the versions going - cool. Why would I want to dump my specification/definition files into someone else’s repo?
From my perspective it is all about the best way of creating the specification/definition files and keeping them in synch with the definitions.
NB: Swagger have the following description of API Definition (which I think is the code file), whereas the document explaining the code file is called (according to Swagger - the API Specification). I mention this 'cause I’d like to ensure I’m referring to the correct item and it looks to me that the wrong term is being applied to this conversation. Spotlight imports the API Definition file, not the API Specification file.

What is an API Definition?

An API definition is similar to an API specification in that it provides an understanding of how an API is organized and how the API functions. But the API definition is aimed at machine consumption instead of human consumption of APIs. An API definition provides information about how the API functions, how it links with other APIs, and the expected results in a machine-readable format. It focuses on defining the API and outlining the structure of the API.

(Nicholaswade) #13

'scuse my ignorance but do you really mean the API Definition file? - (ref Swagger help topic on API Definition vs Specification)

(Taylor Barnett) #14

This is a great point. Different teams have different workflows, and we are working to find a solution that would work for most teams.

To ensure things are kept in sync, we encourage users to take advantage of contract testing to ensure the API implementation that is built matches the specification. It doesn’t necessarily need to be in the same repo for that to happen, but it might make it easier.

This is what I usually use as my go-to for what to call things from the OpenAPI Initiative:

Since it seems like we have cleared up the initial support question, I’m going to close this thread (which I usually do once the initial questions are answered). Let me know if there’s a reason you wouldn’t want me to.

(Nicholaswade) #15

Okay, well, thank you very much for taking the time to clarify issues.

(Taylor Barnett) #16