specmore/spectacular

The opensource project behind the Spectacular tool for maintaining interface specifications

Spectacular ·

Keep your interface specifications Spectacular!

Spectacular helps to make the change review process for interface specifications more visible and organised, resulting in the healthier evolution of interfaces. Ultimately fostering an "API First" culture.

Key Features

• Integration with GitHub for user login and access control to your interface spec files.
• Ability to organise your interface spec files into "Catalogues", making them easier to find.
• Track upcoming versions of the spec files being drafted and what changes are being proposed by visualising all changes on an evolutionary timeline.
• Visualising your interface specifications using graphical documentation tools like Swagger UI for OpenAPI files.

View the Spectacular Demo

See Spectacular in action by visiting our Spectacular Demo website: https://spectacular-demo.specmore.org/

The demo website is integrated with the our own demo interface catalogues in the specmore/spectacular-demo GitHub repository.

Run the Demo App Locally

You can get Spectacular App up and running locally connected to our demo catalogue in no time. Just follow these steps:

1. Clone the Spectacular project repository to your computer
2. Run the start-demo script
3. Navigate to http://localhost in your web browser

For example, on Mac or Linux:

$ git clone [email protected]:specmore/spectacular.git
$ cd spectacular
$ ./start-demo.sh

Application Overview

Before setting up your own installation of Spectacular, it is good to first familiarise yourself with the application's Architecture.

The two key components that this project provides are the:

Component	Docker Hub Image	Latest Version
Web UI
Backend Service

Setup Guide

To get Spectacular working with your own interface specification files (e.g. OpenAPI files) this Setup Guide section will help you get your own installation of Spectacular up and running.

1. Give Spectacular access to your Interface Specification files

Spectacular requires your interface specification files to be stored in git repositories. Therefore, you will first need to configure your git repository hosting solution (only GitHub is currently supported) to give Spectacular access.

This can be done by following the Git Integration instructions.

2. Create your Catalogue Config Manifest files

Spectacular shows the interface specification files that you list in spectacular-config.yml files in any of the git repositories Spectacular can access (as configured in the step above). These catalogue manifest files require your specification files to be organised into collections called "catalogues".

Guidelines for creating a spectacular-config.yml can be found in the Catalogue Configuration Document. Or you can use the Demo project's spectacular-config.yml as a template.

Catalogues inherit any "topics" associated to the GitHub repository that they were configured in.

3. Configure and run your Spectacular instance

After setting up a git integration with your git hosting solution (in step 1. above), you should be ready to configure and run your own instance of Spectacular with access to your spec files.

As described in the Architecture document, an instance of Spectacular is actually built up using 3 services. Before trying to deploy and run your instance, please familiarise yourself with the Configuration guide on how to configure each service using their required Environment Variables.

To deploy and run your own Spectacular instance, we provide the following two options:

1. Using Helm Charts to deploy to your own Kubernetes cluster.
2. Using Docker Compose to deploy to your own Docker host.

3.1 Configure and run using Helm

Please refer to your Spectacular Helm Charts GitHub repository for more information.

3.2 Configure and run using Docker Compose

To help build, configure and run all 3 components in one quick command, a docker-compose.yml file is provided in this repository. (Docker Engine v17.05 or above with Docker Compose is required)

The docker-compose.yml requires 6 environment variables (beginning with the SPECTACULAR_ prefix) to be set corresponding to each of the 6 environment variables in the Configuration guide. It is recommended to create a .env file along side the docker-compose.yml file to capture these environment variables in one place.

For example:

SPECTACULAR_GITHUB_APP_ID=12345
SPECTACULAR_GITHUB_APP_PRIVATE_KEY_FILE_PATH=c:/temp/spectacular-app.private-key.pem
SPECTACULAR_GITHUB_CLIENT_ID=Iv1.41eb20b07bce2547
SPECTACULAR_GITHUB_CLIENT_SECRET=3dd2b1d461df1688dfdd32169cc8075e19c4f59a
SPECTACULAR_JWT_SHARED_SECRET=0c4ec70dbe9cceba51455c402b35d3a5

You can now start your Spectacular instance with the following command:

$ docker-compose up

Once started, your Spectacular app should be available at http://localhost/.

Contributing

Contribution Guidelines

Want to contribute to Spectacular? Please refer to the Contributing Guidelines document for more information on how to do it.

Code of Conduct

The Spectacular project has adopted the Contributor Covenant as its Code of Conduct, and we expect project participants to adhere to it. Please read the full text in our Code of Conduct so that you can understand what actions will and will not be tolerated.

License

Spectacular is MIT licensed.

spectacular's Issues

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

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

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.

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.

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.

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.

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.

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.

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

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.

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

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

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.

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.