Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Make directory structure configurable / optional #57

Closed
rossmcdonald opened this issue Aug 20, 2019 · 8 comments

Comments

@rossmcdonald
Copy link
Collaborator

@rossmcdonald rossmcdonald commented Aug 20, 2019

Related

User story.
As an API developer, I may want to just throw my API descriptions inside the root of the repository (or under some other directory that is not /reference).

Is your feature request related to a problem?
The current directory structure is fairly restrictive, especially when being used with a pre-existing repository that must now be updated to conform to the structure.

Describe the solution you'd like
The directory structure should be customizable, with the ability to be disabled wholesale if wanted.

@erik-hansen

This comment has been minimized.

Copy link

@erik-hansen erik-hansen commented Aug 23, 2019

Yes! We have many repos with more than one component/service where we have OAS files living beside the service that implements the API. It would not make sense for us to recreate the service structure at some root level folder. Instead, I should be able to give you a RegEx that matches the folder name that contains my API/model/doc files. That RegEx should be able to discover more than one folder within the hierarchy of my repo.
Example RegEx: "\/resources\/schema" would pick up the following folders in my Repo to be displayed and manipulated within Stoplight Studio.

  • my-repo/service-a/src/main/resources/schema/
  • my-repo/service-b/src/main/resources/schema/
  • my-repo/component-x/service-y/src/main/resources/schema/
  • my-repo/component-x/service-z/src/main/resources/schema/
@nhuray

This comment has been minimized.

Copy link

@nhuray nhuray commented Aug 24, 2019

IMHO the studio should be viewed exactly as an IDE (Code, Webstorm...), so the API developer should have the ability to create a project (or workspace) and to add as much as API, documentation ... to the project.

The project will be saved in a .stoplight file (for example) saving all preferences.

@ahx

This comment has been minimized.

Copy link

@ahx ahx commented Aug 26, 2019

We usually have one API description per repo:

  • my_repo/openapi/openapi.yaml
  • my_repo/openapi/components/schemas/mymodel.yaml
  • ...

As an API developer, I may want to just throw my API descriptions inside the root of the repository

This is exactly what I need. – Being able to open any openapi.yaml file, make sense of the $refs and ask me where to create (/find) "model" files.

@P0lip

This comment has been minimized.

Copy link
Member

@P0lip P0lip commented Oct 15, 2019

From our design meeting today:

  • the APIs tree becomes a tree showing all files relevant to APIs (i.e. OAS documents), represented as they appear in the filesystem,

  • the APIs tree behaves like a regular file tree meaning you can drag and drop files, rename them, etc.,

  • the rich tree view containing detailed information about currently selected file (see attached draft screenshot),

  • the rich view behaves in the same manner as it does now, with that different it shows nodes relevant only to the chosen document. That means drag and drop, renaming, etc. will still be fully operational and no different,

  • a similar filtering strategy will apply to other trees, such as the docs tree,

  • last but not least, the top tabs will have slightly changed naming, APIs filter, Docs filter to indicate the docs and potential models trees similarly provide a filtered view.

Features we might want to consider:

  • a list of glob patterns can be applied to ignore certain documents in the APIs tree,

  • a new tree for JSON Schema files only.

Draft:
sidebar view draft

TODO

@P0lip P0lip self-assigned this Oct 15, 2019
@marbemac

This comment has been minimized.

Copy link
Member

@marbemac marbemac commented Oct 16, 2019

last but not least, the top tabs will have slightly changed naming, APIs filter, Docs filter to indicate the docs and potential models trees similarly provide a filtered view.

Suggest we leave without the extra "filter" word, we're already space constrained up there :).

a list of glob patterns can be applied to ignore certain documents in the APIs tree,

<3 for potential separate issue to tackle later.

a new tree for JSON Schema files only.

<3 - "Schemas"? "Models"? We are running out of space though, might have to brainstorm options.

@erik-hansen

This comment has been minimized.

Copy link

@erik-hansen erik-hansen commented Oct 19, 2019

From the screenshot, it looks like I still must have "reference" as the root folder - this would not work for us. Please be sure you just display OAS/MD files within the directory structure as is. I would be even happier to specify a RegEx that helps you identify only the directory structures you should scan - so it doesn't take so long to load a project, like now...

Thanks! Looking forward to this being implemented!

@rossmcdonald

This comment has been minimized.

Copy link
Collaborator Author

@rossmcdonald rossmcdonald commented Oct 21, 2019

@erik-hansen The last screenshot was taken from a project that was already in the previous format, but the requirement on a reference directory will be completely lifted as soon as this change lands in a release. For example, here is a project with the API specs stored at the root of the repo:

image

And regarding:

I would be even happier to specify a RegEx that helps you identify only the directory structures you should scan - so it doesn't take so long to load a project, like now...

Yep, completely agree. I'll create a separate issue around this as soon as this issue is closed and we verify the problem is still present with the new sidebar format.

@StoplightDeb

This comment has been minimized.

Copy link

@StoplightDeb StoplightDeb commented Oct 25, 2019

Talked through with @rossmcdonald, looks good for next release on October 30 release, closing.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
7 participants
You can’t perform that action at this time.