specmore/spectacular

The opensource project behind the Spectacular tool for maintaining interface specifications

spectacular's Issues

Ability to hide all previous version in spec evolutions

Repositories with automated tagging on builds may cause a long list of old versions to show in the spec evolution view on the interface details page.
It might be good to be able to hide/collapse this bottom part of the spec evolution. Potentially having it collapsed by default.

Default Swagger UI to load with expanded tags

Default Swagger UI to load with expanded tags so that all the path/operations are shown immediately

Change login workflow to first show a login selection page

Currently the login workflow uses GitHub Login by default. Therefore after logging out the user will just get logged straight back in again.

We need to reintroduced a login selection screen even though the only option will be to login using GitHub.

Pull Request data is cached indefinitely

The PullRequestRepository component needs to be changed to have a lifetime of just the request scope to allow the cache to be isolated to just each individual request. Currently it is living as a singleton for the full lifetime of the application.

GitHub App create installation access token API endpoint has been deprecated

As per this GitHub blog post, the old installation access token API endpoint for GitHub Apps has been deprecated.
As of October 2020, v0.1.1 has now stopped working because of this.

Better surfacing of errors when problems occur during the login workflow

Currently when errors occur in the login in process, they are not logged clearly and no error is displayed to the user.

refresh UI

It's time to clean up the UI!

Things to do:

• Add logo
• Add favicon
• Add color palette
• Add custom semantic ui theme files

Ability to see previous versions of the specification for an interface

As of v0.1.1 of Spectacular, for a given interface, it is currently only possible to view the "Latest agreed version" of the interface's specification and any number of versions with "Proposed Changes" currently open against it.

As seen in the screen shot below, it would be good to show a list of previous versions of the interface specification.

The previous versions could be determined by identifying git tags that were created for each previous version of the specification file.

Limit GitHub SSO scope to just verify user identity

Currently when logging in using GitHub SSO into the Spectacular app, the following permissions are requested by Spectacular:

• Verify your GitHub identity
• Know which resources you can access
• Act on your behalf

The only permission really needed is the "Verify your GitHub identity" permission to allow Spectacular to function.
The SSO OAuth scope should be reduced to at least not request access to act on behalf of the user..

Pull requests for private repositories aren't showing up in the spec evolution.

It appears for spec files kept in private repositories, Spectacular isn't picking up any pull requests against those files.
It is likely a missing permissions problem with the GitHub app resulting in the GraphQL query not returning any PR information.

Make Catalogue Manifest schema extensible to prevent breaking old clients when using new versions

When adding new fields to a Catalogue Manifest that are in a newer version, it currently breaks v0.1 clients.
Remove restrictions on additional properties from the Catalogue Manifest schema to make the client a tolerant reader and ignore fields it doesn't recognise.

Refactor the remaining backend API endpoints and frontend clients to use the OpenAPI spec approach and generated code

Existing axios based API client class has two remaining endpoint functions:

• fetchInstallation
• fetchUserInfo

Ability to filter catalogue list on the Available Interface Catalogues page

There should be some way for users to filter the catalogues listed in the Available Interface Catalogues homepage to make it easier to find specific catalogues.

Some ideas to filter by:

• Specific topics / labels
• Specific teams

Using relative paths in $ref definition

Sales & Service have a set of API Specs for the BT Ocean API defined in this repository -> https://github.com/sky-uk/ott-sas-partner-gateway/tree/master in folder proposed-apis. We have integrated these with spectacular, see spectacular-config.yml

link to API in spectacular -> https://spectacular.dev.cosmic.sky/catalogue/c2t5LXVrL290dC1zYXMtcGFydG5lci1nYXRld2F5L3NwZWN0YWN1bGFyLWNvbmZpZy55bWwvc2Fz/interface/account?ref=master

I have noticed that the rendering of the API failed for definitions using the $ref annotation and a relative path - such as proposed-apis/account.yaml#L62-L67 see attached screenshot.

Spec files larger than 1MB can't be retrieved from GitHub

Spec files larger than 1MB (like this one) can't be retrieve using the existing approach of using the GitHub Repository Contents API.
The following error message is returned:

org.springframework.web.client.HttpClientErrorException$Forbidden: 403 Forbidden: [{"message":"This API returns blobs up to 1 MB in size. The requested blob is too large to fetch via the API, but you can use the Git Data API to request blobs up to 100 MB in size.","errors":[{"resource":"Blob","field":"data","code":"too_large"}],"documentation_url":"https://docs.github.com/rest/reference/repos#get-repository-content"}]

It is likely that the GitHub Blob API needs to be used instead.

User menu item isn't shown when connecting via https

The user menu item on the right side of the menu bar doesn't show when loading the demo site. https://spectacular-demo.specmore.org/

Version Details:
Version - 0.1.0+546
SHA - c4baab1

Browser Console Output

main.a041a35a705d29259c91.js:176 VERSION: 0.1.0+546
main.a041a35a705d29259c91.js:176 SHA: c4baab1
spectacular-demo.specmore.org/:1 Mixed Content: The page at 'https://spectacular-demo.specmore.org/' was loaded over HTTPS, but requested an insecure XMLHttpRequest endpoint 'http://spectacular-demo.specmore.org/login/'. This request has been blocked; the content must be served over HTTPS.
main.a041a35a705d29259c91.js:176 TypeError: Cannot read property 'status' of undefined
    at main.a041a35a705d29259c91.js:176
    at /async https:/spectacular-demo.specmore.org/main.a041a35a705d29259c91.js:176
    at async a (main.a041a35a705d29259c91.js:176)
a @ main.a041a35a705d29259c91.js:176
async function (async)
a @ main.a041a35a705d29259c91.js:176
(anonymous) @ main.a041a35a705d29259c91.js:176
_s @ main.a041a35a705d29259c91.js:60
Fu @ main.a041a35a705d29259c91.js:60
t.unstable_runWithPriority @ main.a041a35a705d29259c91.js:68
Ko @ main.a041a35a705d29259c91.js:60
Iu @ main.a041a35a705d29259c91.js:60
(anonymous) @ main.a041a35a705d29259c91.js:60
R @ main.a041a35a705d29259c91.js:68
k.port1.onmessage @ main.a041a35a705d29259c91.js:68