apinf/openapi-designer

Design interface for creating Open API (Swagger) specification files

OpenAPI designer

Design interface for creating OpenAPI (Swagger) specification files. Live demo

Setup

0. Have a Node.js install that's not way too old (v4+ should work for everything).
1. Install Aurelia CLI (npm install -g aurelia-cli)
2. Clone this repo (git clone https://github.com/apinf/open-api-designer.git)
3. Install dependencies (npm install)
4. Build the code (au build) and open index.html OR run the webserver integrated in Aurelia using au run and open the URL that is printed after building (usually http://localhost:9000)

Docker

0. Follow setup instructions step #2
1. Run docker build -t openapi-designer . (Run with --build-arg env=prod to compile the production version.)
2. Run docker run -p <port>:80 openapi-designer replacing <port> with the port you want the app to be accessible at.
3. The designer should now be accessible at http://localhost:<port>

Development Status

Resources

• OpenAPI Specification

openapi-designer's Issues

Divide design form into sections

The design form is currently very long, and expected to grow. Design/research some possible solutions for making the form shorter, e.g. a multi-step wizard or collapsible sections. Make changes to the form structure based on the design decision and possibilities for the autogenerated form.

Consider branding the designer with APInf elements

These elements could be logo, title, colors

@Nazarah Let's look at the UI and discuss the options for branding the designer

Add info tip to indicate purpose for License sub section

Issue

It is not clear to the user what is the purpose of the License sub-section. It would be prudent if is mentioned why License is needed and what value should be added to related fields.

Solution

Add an info tip describing the purpose of License subsection and what value should be given in the fields.

Contact field: purpose for "URL" and "Email" field is not clear to the user

Issue

It is confusing for the user what is the URL for. His/her home page or anything else. Similar case is with "Email" field.

Enhancement

Add a info tip letting people know what is the purpose of the URL field and what value should be added here. Same goes for email field as well.

Consider changing from MIT to AGPL license

https://tldrlegal.com/license/mit-license
https://tldrlegal.com/license/gnu-affero-general-public-license-v3-(agpl-3.0)

After a while preview window stops showing added field values

Under "Paths" section, user was giving values for Response subsection.
None of the values added appeared in the preview window under Response.
Afterwards in subsequent sections, no values added in the editor appeared in the preview window.

Add button to download YAML

Some developers may prefer their API docs in YAML format. Add a button to allow developers to download the documentation in YAML format. Optionally, nest the JSON and YAML buttons together as a dropdown:

Create wireframe for overall application design structure

We are currently designing the application incrementally, without discussing how the overall UI should look. Wireframes are a good way to explore options for the UI layout, because they are simple to create and throw away.

Start sketching a few UI wireframes, to explore possible designs.

Branding of Open API Page

Low fidelity prototype describing how the current view can be migrated to standard APINF branding

Wirefames

1. Homepage:
   

2. About page
   

3. Contributor page
   

keeping the option of chatbot instead of contact form.
Whenever user comes to open-api-designer, chatbot would open up and request the user to provide their name and email address so that someone from APINF can get back to them

Replace the item button with more meaningful button

Please use a more meaningful label for the item button. You are using the item button for instance in Paths section, while for instance in MIME type the label is the item = MIME type you are adding or deleting.

Compare the following:

Research and design a persistance layer

User stories

As an API designer,
I want to be able to save my document draft
so that I don't risk loosing what I have edited so far, if e.g. my browser crashes or I run out of battery on my laptop.

As an API designer,
I want to be able to save my document
so that I can continue editing it some other time.

Make sure the Swagger file validates

Ensure that the json that is parsed from the user input passes Swagger validation. You can use for example this validator to check: http://bigstickcarpet.com/swagger-parser/www/index.html

Paste the output you are producing and see if it validates. Take necessary action to make it pass. For example, the json probably needs to start with Swagger version even if it was not part of the form UI.

Path field doesn't maintain Regular expression checking. It accepts any sequence of characters

Path GUI Bug

1. On adding a new Path, the GUI of panes overlap with each other
2. On Adding Path attribute value, it comes out of the blue pane
   ( above cases also happens with Security Definitions section)

Redesigning UI for editor and preview window

• designing low fidelity prototypes for the UI

Add button to reset form

It is difficult to reset the designer interface. Even a 'clear all cache' refresh leaves the form populated with previous values.

Feature request

Add some way for users to manually reset the form values.

On loading the page for the 1st time, user doesn't know at which part of the documentation is in front view

When the page is loaded for the 1st time, the Info section should be selected/highlighted.
But it doesn't happen.
When user browse other sections and then clicks on Info section, it then appears as selected.

Add an alert when user tries to download invalid swagger

If the user tries to download a swagger file that, for example, has some required fields still empty, there should be an alert telling the user to fill the required fields before downloading the json.

Github ribbon covers clear form button

This is especially a problem on slightly smaller screens.

Add responses definitions object

This object is a part of the OpenAPI-Specification.

After adding a scheme, the action buttons disappears unless mouse is hovered on the scheme section. Also there are multiple instances of the same action pane appearing for each scheme field

http://g.recordit.co/lPDFztDn4Q.gif

Make Preview window floating/sticky

Issue

For longer sections in the Open API documentation, the preview window gets hidden once user starts to scroll down to fill in fields. It would be better if the preview window was floating/sticky to the view as user scrolls down. This would ensure user gets to always see how the preview of the documentation look s.

Enable linting for code quality/consistency

Our project does not currently have linting enabled. Using a linter helps enforce code style and quality, and can prevent some common types of bugs.

Enable eslint for this project and add basic linter rules.

Docker container for open api designer

Swagger version number disappears when starting to fill out form

When the form first renders, the Swagger version is visible in the JSON preview. After editing one or more form fields, the swagger version no longer appears.

Info icons and help texts for fields

Place an icon to the same row as the tile. The icon could e.g. be a circle with letter 'i'.
When user clicks over the icon, a help text explaining the purpose of the field appears.

Implement PUT, POST, DELETE operations for path

A single API path can have several operations: GET, PUT, POST, ALLOW. Allow user to add more than one operation for a path and to select the type of each operation. Each operation will then have subfields defined in Operation Object, which were already implemented for GET (as agreed, first only the fields with type string)

References

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#pathItemObject
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#operationObject

Example picture from Swagger UI for Petstore API:

Usability testing

Different error message in paths.methods.externalDocs.url

The URL field invalid URL error message inside the externalDocs object differs from other fields.

The schema for both objects in the image is exactly the same. Both are imported from schema/externaldoc.js

This is the error in all other URL fields:

And this is the error in paths.methods.externalDocs.url:

On clicking "Add New Item" button under Paths section, the entire GUI gets disappeared.

• OS: Windows 8
• Browser: Chrome, FF

Repeating sections in Paths -> Methods

Right now when a method is added under a path, Schemes, Consumes, Produces and Parameters sections appear along with the new fields (Method Types, Tags, Summary, Description, External Documentation: URL, Description, Operation ID, etc.).
It seems the Schemes, Consumes, Produces and Parameters sections are added repeatedly.
Is it done intentionally or is this a bug?

Add a CONTRIBUTING.md file

We should add contribution guidelines.

Some things to include:

• ESLint info
• Indent length & type

Add parameters definitions object

This object is a part of the OpenAPI-Specification.

Incorporate APINF header and topbar in Open API Designer page

open question: should we link this page with regular APINF platform? (a new menu in the Topbar)
Or should we have this option as an "Add" funtionality (e.g. similar to Add API)

Cover the missing fields in Open API specification

Check which top level and children fields are missing from the form and add them to the relevant sections.

You can break this issue into smaller tasks in the Github issue list if you want.

Related

• #29
• #30

Consider blending form-based designer with rich preview

Open API Designer

We are currently building a simple form-based design tool, with code preview on the right.

Swagger Editor

The Swagger Editor project has a code editor on the left with a rich preview on the right.

Hybrid approach?

What are some thoughts and considerations about possibly combining the form-based designer with the rich preview, for a best of both worlds?

Make API Documentation Section Pane floating

Issue

Some sections of the Open API Designer is longer. So on scrolling down, the Section Pane gets hidden on top. It would be prudent so make the section pane floatable. This would allow the user to be aware of where s/he is currently in the documentation editor.

It is not clear to user if "Host" and "Base" is part of License subsection

Issue

When License subsection is open in expanded view, it becomes difficult to understand if Host and Base fields are under this. The dividing lines are not clear enough to distinguish Host and Base fields from that under License.

Solution

• Indicate if the fields are related to each other with info tip OR
• if Host and Base fields are separate from License subsection, make the divider lines more visible. Possibly add the fields under another Subsection.

Add descriptive comments to index.js

Currently, index.js contains 3 comments out of 136 lines. Of the three comments, two are 'TODO' and one is "this isn't working".

Comments are needed when reading code, so that we understand

• what the code is doing and
• why it is written how it is.

While JavaScript is mostly readable, comments are written in human language, so can be understood much easier by other people reviewing the code.

In sort, make sure to have about a 60% code 40% comments balance in all code for this project.

Info text for Host field should be more intuitive

Issue

The info message given for Host field is vauge. It doesn't clearly state the purpose of the field, how is it related to Base field and what example value should be given in it.

Solution

Give intuitive text explaining the above description for Host field.

Add definition object editor

An editor for definitions needs to be added in order to implement things such as body and response schemas

Values in the preview window get out of the window boundary

Fix paths.methods output format

The output is currently is an array, but it should be a map with the method as the key.

Make 0.1.0 release

We should make an initial release soon. As a convention, our releases should follow semantic versioning. The 0.1.0 release can be made against the current master, or at a previous commit.

Can't delete fields in response example

Fields can't be removed from examples if the value is an object (path->method->response->example). Even removing it with the raw JSON editor won't work (it just replaces it with null)

Consumes & Produces sections: Add info tip explaining what is MIME type, why it is needed and possible value example

Issue

In usability testing, participant had to google to know what is MIME and what can be its possible value.
It is not clear in the view why MIME type is needed.

Solution

1. Add info tips in Consumes and Produces sections giving information about what are these and why they are needed.
   2.There should be info tip stating the above information in Consumes and Produces Section

Implement fixed fields for Parameter Object

Parameter Object is a field for Operation Object. It describes the parameters an API call to a particular endpoint can/must get. For example, if you need to DELETE an item from an endpoint, you would need to know the id of the item and the id would be a parameter (typically a path parameter).

Reference:

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#parameterObject

See table Fixed fields in section Parameter Object for fields to implement.

Parameter example for endpoint and operation from Swagger UI / Petstore

Support importing spec files

It would be useful to be able to import an API specification file into the editor.

Icons not rendering in demo site

On the demo site, the icons next to required fields and validation messages are not rendering:

On page reload, preview window disappears completely

When user fills up fields in several sections in the editor,
if s/he reloads the page, the values given remains in the respective fields,
but the preview window doesn't appear at all.