apicurio/apicurio-studio

Open Source API Design

The apicurio-studio project (Open Source API Design Studio)

Summary

This is the official Git repository for the Apicurio Studio project: http://www.apicur.io/studio

The Apicurio Studio project is a standalone API design studio that can be used to create new or edit existing API designs (using the OpenAPI or AsyncAPI specifications).

Get the code

The easiest way to get started with the code is to create your own fork of this repository, and then clone your fork:

  $ git clone [email protected]:<you>/apicurio-studio.git
  $ cd apicurio-studio
  $ git remote add upstream git://github.com/apicurio/apicurio-studio.git

At any time, you can pull changes from the upstream and merge them onto your main:

  $ git checkout main               # switches to the 'main' branch
  $ git pull upstream main          # fetches all 'upstream' changes and merges 'upstream/main' onto your 'main' branch
  $ git push origin                   # pushes all the updates to your fork, which should be in-sync with 'upstream'

The general idea is to keep your 'main' branch in-sync with the 'upstream/main'.

Building apicurio-studio

Requirements

• Maven 3.x
• Java 11 or 17 (recommended)
• Node.js and NPM

Contribute fixes and features

Apicurio Studio is open source, and we welcome anybody who wants to participate and contribute!

If you want to fix a bug or make any changes, please log an issue in GitHub describing the bug or new feature. Then we highly recommend making the changes on a topic branch named with the GitHub issue number. For example, this command creates a branch for an issue with number 1234:

  $ git checkout -b apicurio-studio-1234

After you're happy with your changes and a full build (with unit tests) runs successfully, commit your changes on your topic branch. Then it's time to check for and pull any recent changes that were made in the official repository:

  $ git checkout main               # switches to the 'main' branch
  $ git pull upstream main          # fetches all 'upstream' changes and merges 'upstream/main' onto your 'main' branch
  $ git checkout apicurio-studio-1234   # switches to your topic branch
  $ git rebase main                 # reapplies your changes on top of the latest in main
                                      # (i.e., the latest from main will be the new base for your changes)

If the pull grabbed a lot of changes, you should rerun your build to make sure your changes are still good. You can then either create patches (one file per commit, saved in ~/apicurio-studio-1234) with

  $ git format-patch -M -o ~/apicurio-studio-1234 orgin/main

and upload them to the JIRA issue, or you can push your topic branch and its changes into your public fork repository

  $ git push origin apicurio-studio-1234         # pushes your topic branch into your public fork of apicurio-studio

and generate a pull-request for your changes.

We prefer pull-requests, because we can review the proposed changes, comment on them, discuss them with you, and likely merge the changes right into the official repository.

Please try to create one commit per feature or fix, generally the easiest way to do this is via git squash. This makes reverting changes easier, and avoids needlessly polluting the repository history with checkpoint commits.

Code Formatting

When you are hacking on some apicurio-studio code, we'd really appreciate it if you followed the apicurio-studio coding standards. If you're using Eclipse, you can find a code formatter config file here:

.config/eclipse/apicurio-eclipse-formatter.xml

You should be able to import that guy straight into Eclipse by going to Window->Preferences :: Java/Code Style/Formatter

If you're using Intellij, you can find a code formatter config file here:

.config/intellij/apicurio-intellij-formatter.xml

apicurio-studio's Issues

Error when adding a Response to an Operation

TypeError: Cannot read property '200' of undefined
    at Oas20Responses.response (http://localhost:8080/node_modules/oai-ts-core/bundles/OAI.umd.js:2255:31)
    at NewResponseCommand.execute (http://localhost:8080/studio/pages/apis/%7BapiId%7D/editor/commands/new-response.command.js:50:44)
    at CommandsManager.executeCommand (http://localhost:8080/studio/pages/apis/{apiId}/editor/commands.manager.js:59:17)
    at ApiEditorComponent.onCommand (http://localhost:8080/studio/pages/apis/{apiId}/editor/editor.component.js:197:24)
    at View_ApiEditorComponent14.handleEvent_0 (/StudioModule/ApiEditorComponent/component.ngfactory.js:901:45)
    at View_ApiEditorComponent14.eval (http://localhost:8080/node_modules/@angular/core/bundles/core.umd.js:12774:41)
    at SafeSubscriber.schedulerFn [as _next] (http://localhost:8080/node_modules/@angular/core/bundles/core.umd.js:4116:40)
    at SafeSubscriber.__tryOrUnsub (http://localhost:8080/node_modules/rxjs/Subscriber.js:223:16)
    at SafeSubscriber.next (http://localhost:8080/node_modules/rxjs/Subscriber.js:172:22)
    at Subscriber._next (http://localhost:8080/node_modules/rxjs/Subscriber.js:125:26)
    at Subscriber.next (http://localhost:8080/node_modules/rxjs/Subscriber.js:89:18)
    at EventEmitter.Subject.next (http://localhost:8080/node_modules/rxjs/Subject.js:55:25)
    at EventEmitter.emit (http://localhost:8080/node_modules/@angular/core/bundles/core.umd.js:4090:80)
    at OperationFormComponent.addResponse (http://localhost:8080/studio/pages/apis/{apiId}/editor/components/operation-form.component.js:316:24)
    at CompiledTemplate.proxyViewClass.View_OperationFormComponent0.handleEvent_554 (/StudioModule/OperationFormComponent/component.ngfactory.js:4567:34)

Determine if a "standalone" angular 2 component can be used in a non-angular2 app

For this ticket, try to use the angular 2 API editor test component created in #1 in a non-angular 2 app.

This can be a simple static web site, where some custom javascript is included which would create the component and display it somewhere on the page. Explore possible display options, with an iframe being the "last resort". :)

What we're shooting for here is functionality similar (not necessary the SAME as) to something like the ACE editor. I.e. the ability to somehow create the API editor angular 2 component and embed it on a web page, and then interact with its public api (setValue, getValue, etc).

Does apicurio-studio need i18n

• Do we need it?
• What's the best approach for this app?
• Should we use the Angular 2 i18n toolset. It seems vastly better than Angular v1's stuff.

Add Existing API: Use GH Search to show suggestions

Suggestion: Use GH search to show some suggestions (obvious patterns might be conventions such as swagger.json, oai.json, *.json, or whatever). So I can enter github.com/msavy/foo-repo and it’ll show some candidates.

Could either expand the form fields or perhaps implement type-ahead.

Package apiman-studio as a standalone app (for tech eval)

Need to create a full build/packaging process that results in a single downloadable server that can be run for tech evaluation purposes.

Signpost whitespace in error-prone locations

In various input areas you can add whitespace, and it can be non-obvious - seems like a possible hard-to-find user-error location (e.g. path, query params, etc). “/foo “ or “/ foo” etc. Might be able to signpost that whitespace in a useful way, for example by highlighting it in a different colour or outline it as a cell, for instance.

Create API Page: Validate that the API definition exists (or can be added) in github

Now we just assume that the resource either exists or can be created. Let's verify that when adding it (i.e. the New API Page).

Improve the "Loading" screen

The loading screen is what the user sees when the application is initially loading. The markup for this is found in the host/index page and should be improved (currently it's just "Loading..." text!).

Consider using Yarn?

https://yarnpkg.com/

It's a project from Google, Facebook and co to provide a much more reliable experience for JS package resolution and reproducibility. In particular it seems to handle dependency locking in a more sensible way (e.g. updating its lock file when you update and add deps rather than waiting for you to do it manually).

Furthermore it claims to be much faster and have caching that actually works properly.

Yes... new week, new JS project; this seems worth checking out, though.

Add Travis CI with nightly snapshot releases

We're already familiar with Travis, of course.

A new feature makes it more convenient to do regular snapshot releases:
https://blog.travis-ci.com/2016-12-06-the-crons-are-here

Create New API: Suggest a location+name for OpenAPI doc

If there is an existing convention for where the OpenAPI doc should be located and what it should be called, pre-populate that in the form when creating a new API.

Change color of query param name in query param table

When editing the query params for an operation, the names of the params are colored the same as the path param elements in the path. The color for query params should be different.

APIs Page: Implement "APIs" page to list/filter/search for APIs being managed

The APIs page is currently a placeholder - it should be a functional listing/search page.

Improve the Add/Create API UI

The Add API user experience must be improved to make it easier for users to get started.

Perhaps a new Add API Wizard which can walk the user through quickly adding an existing API (already exists in github) OR creating a new API (no file yet exists in github).

Support all HTTP codes in the New Response dialog

When adding a response to an operation, you must pick a valid HTTP response code. The drop-down only has a couple of them - we should include them all.

API Details Page: Support in-line editing of the API name and description

The user should be able to change the name of the API and its description.

Absolute position of editor inconsistent across browser

The editor needs to be at top: 67px for firefox but top: 68px for chrome.

Find a better way to position the editor on the page!

Display *something* when a path has zero operations

When a path has no operations, there is still a large space in the master view where the list of operations supported by the path would normally go. Something should be in that space, even if it's just a warning.

API Details Page: Disable "Manage Tests" and "View Documentation" buttons

These will be implemented in a later phase.

Handling of Path Parameters

We currently do not let the user describe their path parameters. The path parameters should be displayed in the Path Form and editable there. Sadly the OpenAPI spec requires the path params to be defined at each of the operations, rather than on the path itself. For this reason, the editor should allow the user to edit them on the Path Form, but the changes would need to be applied to all operations.

Changes needed:

• Display table of path params on the Path Form (only if the Path has at least one operation)
• Path Params are editable on the Path Form
• Changes made to path params are applied to all operations in path
• New operations must inherit path params from existing Operation(s)
• First newly created operation for Path should automatically create required path parameters based on the path format

Add extra commit message (optional) as a commit comment

The UI lets the user include a short summary and then a longer description when saving changes to APIs. Currently the description is being dropped - it should get added as a commit comment.

Login: Use access-token flow for all auth (even when not using 2FA)

This would make it so we never need to save the username/password in local storage.

Make the "edit all path params" optional

Right now if you change the description or type of a path parameter, ALL of the path params for the operation will be changed. This should be optional so that the user can alternatively provide different values for description and type of the param for different operations in the same path item.

Create API Studio project website

We obviously need a project homepage for the studio. A couple of domains have been purchased for this purpose. The project page must simply have basic information about the project and links to download or otherwise evaluate the software (along with other standard OSS project information).

Create New API: Add "own userspace" to the Organization dropdown

Right now the user's space (e.g. EricWittmann) is not included. This makes it impossible to create new APIs within a repository located in the user's space.

All Pages: Implement Logout for the user

Clicking logout should log the user out and reload the app (presumably showing the Login screen).

Generate Vert.x client and server stubs

It would be fantastic (if we get that far) to have a way to generate Vert.x client and server stubs from the Swagger doc.

Some Googling reveals some demand for it, and there is no such functionality at the moment.

Implement github authentication for "standalone" UI mode

The standalone (server-less) version of the studio works exclusively with github. We should require the user to authenticate via github's OAuth. This way we will know who is logged in and we can avoid asking for credentials to manage an API resource.

Don't store passwords in the clear!

Any time a password is stored, even though we're currently storing them in browser local/session storage, they should still not be in the clear. They should at least be obfuscated.

API Listing: Filter box doesn’t support wildcard/simple regex patterns (e.g. *store)

Specification and enforcement of charset

There may be some interesting considerations to whether we need to allow the user to specify the charset their API supports and therefore constrain the characters they are allowed to enter for paths, etc, to avoid breakages.

Commonly it would be UTF-8/16 or similar, but I can imagine some older APIs might only support a more limited charset.

API Editor Page: Warn the user when navigating away from dirty API Editor

If the API editor is dirty, navigation should be blocked without the user confirming.

Wrong usage ?

Hello guys,

I would like to have a try to the apiman designer.
Not sure if I'm doing something wrong, but I've created a github repository including a OAI definition (https://github.com/brasseld/apiman-studio-test).

It seems that there are some CORS issues:

Also, my github password appears in clear in the session storage and I'm not sure it's a good idea.

Thanks for your feedback.

APIs Service: When the user accesses an API, push it forward in the list

When the user accesses an API in the UI, that API should be pushed up the list of "recent apis". This way the most recently accessed APIs will always be the ones displayed in the Dashboard and in the vertical nav.

No feedback when incorrect OTP provided

Submit button reactivates with no message about the auth failure (can be seen in console shown in details section below).

Console Output

[GithubAuthenticationService] logging in user msavy  auth-github.service.js:105:9
[GithubAuthenticationService] Fetching authenticated user information.  auth-github.service.js:217:9
(1) [GithubAuthenticationService] call to /user failed with:  Object { _body: "{   "message": "Must specify two-fa…", status: 401, ok: false, statusText: "Unauthorized", headers: Object, type: 2, url: "https://api.github.com/user" }  auth-github.service.js:168:17
[GithubAuthenticationService] logging in user msavy  auth-github.service.js:105:9
(2) [GithubAuthenticationService] call to /user failed with:  Object { _body: "{   "message": "Must specify two-fa…", status: 401, ok: false, statusText: "Unauthorized", headers: Object, type: 2, url: "https://api.github.com/authorizatio…" }  auth-github.service.js:144:17
[GithubAuthenticationService] logging in user msavy  auth-github.service.js:105:9
(3) [GithubAuthenticationService] call to /user failed with:  Object { _body: "{   "message": "Must specify two-fa…", status: 401, ok: false, statusText: "Unauthorized", headers: Object, type: 2, url: "https://api.github.com/authorizatio…" }  auth-github.service.js:144:17

1. Correct username/password but no OTP (box appears)
2. Incorrect OTP
3. Incorrect OTP (again).

---

It looks like the logic doesn't distinguish between needing to show the OTP box (because it hasn't been provided yet) and the OTP entry being incorrect.

Support configurable keyboard shortcuts for editor

The editor will have a variety of keyboard shortcuts for certain actions. For example, Ctrl-z to undo the last command/action. It would be nice if the user could configure those keys.

API Editor: Validate the API

Whenever the API is changed, validation should be performed. The editor needs a way to visually indicate validation errors to the user.

API Detail Page: Link from the Top Collaborators to github

Link from the list of collaborators to a sensible place in github.

APIs Service: Retrieve "collaborators" information from github

The collaborator information is currently hard coded. It should be retrieved by getting the information from github (the list of commits).

Create a simple "api editor" component in angular 2 for testing purposes

The reason to create this API Editor component (which should be a simple <textarea/>) is to test and confirm the ability to embed such a component in other JS applications/web sites.

The editor component should have a very simple API:

• Set value
• Get value
• Fire event: onChange when the editor's value changes

It should be created in its own repository (or alternatively its own sub-directory of apiman-studio).

Better handling of Errors in Create API form

If the create fails, then we currently don't do anything useful with the resulting error. We should display it on the screen and provide some way for the user to proceed/retry. Reasons why it might fail:

• User doesn't have write privs to the repository
• A file already exists at the provided repo location
• Solar radiation

Add <!DOCTYPE html> to index

Currently it's running in quirks mode, and when standards mode is enabled the CSS breaks.

Set up Webpack

Set up application to work with Webpack.

API Details Page: Link to the API resource

Right now the resource URL is displayed in a text input so it can be easily copy/pasted. Instead, link to it in github.

Confirm that a "standalone" angular 2 component can be easily used in project Y (and how)

The simple API Editor test component created in issue #1 needs to be packaged/bundled as a standalone angular 2 component so that it can be used in other projects.

For this ticket, create a new, standard angular 2 application so that you can consume the API Editor test component from #1.

This new angular 2 application should be logically separate from the editor test component.

This ticket is mostly about figuring out how to package/bundle the editor test component in a way that is easy for unaffiliated angular 2 projects to consume it (presumably via npm node_modules).

Add support for two-factor github auth

If users have enabled two factor auth in github, then basic auth will fail. Documentation found here:

https://developer.github.com/v3/auth/#working-with-two-factor-authentication

API Details Page: Implement ability to Delete an API

This should simply "unmanage" the API by removing it from the studio. It should not delete the source resource (the openapi file itself). The user should be notified of this.

New API Page: Add drag-and-drop support - URL of github resource

Right now the user has to manually fill out the New API Page form. Additionally, we should have a way for the user to drag and drop a URL of a github resource into a drop-target. The studio will then fetch the content of the resource and auto-fill the form with Name, Description, and repository resource info.

API Editor: Add Context-Help in various useful places

Minimally this should include:

• All Section Headers in the editor (operation form, path form, main form, master area, etc)
• All modal dialogs

The ? icon that triggers the help should only appear when the user hovers over the appropriate area, to avoid a lot of clutter.

Implement Save/Commit API changes

Currently the API can be modified by the editor, but the changes made cannot be saved back to GitHub. This obviously needs to change!