In December we released powerful new functionality in SwaggerHub, API Standardization, which gives teams the ability to build and enforce API style guidelines at scale.
Before the New Year, we hosted a free training, Build and Enforce API Standards at Scale with Swagger. During the 60-minute session, we did a live demonstration of the new functionality, and discussed how organizations can standardize their API design with Swagger tools and the OpenAPI Specification.
More than 1,000 people joined the session and we received a ton of questions for how teams can use SwaggerHub and OAS to put these strategies into action. But we also heard from a lot of people that were not able to make it to the webinar due to busy end of year schedules.
We are excited to announce that on January 10th we are hosting a special replay of the webinar! As a preview, we also wanted to share and answer the top questions from the first session. Check them out below and make sure to reserve your spot for the webinar on January 10th at 10am & 2pm ET.
Does the new API Standardization feature in Swaggerhub support the option to add custom rules from our internal style guides?
This functionality is not supported in the initial release of the feature. If you do have rules you’d like to see added to API Standardization, please reach out to us on twitter @swaggerhub. We want your feedback so we can continue to evolve the tool to meet the needs of API teams.
When we enable API Standardizaton in SwaggerHub, will that apply to all APIs and each version of the API?
API Standardization lets you set rules at an organization level and have those rules apply to all of the API definitions within your catalogue in SwaggerHub. When you create a new version of the definition or update an existing version, the feature will automatically validate and provide feedback based on the rules defined in your account.
Does API Standardization work for the latest version of the OpenAPI Specification, OAS 3.0?
Yes, API Standardizaton supports OAS 3.0 with a few rule exceptions. You can see the full list of rules and exceptions below:
Operations
-
Summary should start with upper case and end with a dot
-
Operation description must be present and non-empty string
-
Operation must have a tag and non-empty string (OpenAPI 2.0 only)
-
Operation must have one and only one tag
-
Operation must have at least one 2xx response
API Info
-
API title must be present and non-empty string
-
API description must be present and non-empty string
-
API contact must be present and non-empty string
Models
Do you have an advice for how we can generate a definition from the code? We’re having trouble generating a useful interface for our existing APIs?
There are open source tools and libraries that can help with generating an OpenAPI definition from an existing API. The Swagger team supports some of these libraries for generating OAS from your existing APIs, and the rest our maintained by the OAS community:
You can explore other open source tools that support OAS here.
Can we create common models that can be used and referenced across multiple specification files?
This functionality is supported in SwaggerHub through the Domains feature. Domains are reusable components that can be stored in SwaggerHub and referenced within a definition from the SwaggerHub editor.
A domain can contain the following components (any combination of them):
-
Definitions – Data models that describe your API inputs and outputs.
-
Path items – API paths (such as GET, POST, PUT operations) that can be reused across APIs.
-
Parameters – Parameters for an API call: path parameters, query string parameters, custom headers, body fields.
-
Responses – The responses returned by API calls: HTTP status codes and the response data model.
Learn more
Does SwaggerHub work with our source control repository?
SwaggerHub offers source control integrations with GitHub, Bitbucket, and GitLab. The integration allows you to synchronize your API definition, auto-generated server code or client SDK with an existing repository. The synchronization is done every time you save the API in SwaggerHub. You can fully control which files will be added, updated or ignored in the target repository.
Rather than hosting your OAS definition in various repositories and branches in GitHub, you can now leverage SwaggerHub as the source of truth for all your API design and documentation needs while still keeping them in sync with your source code in GitHub or any other source control repository.
Learn more
What measurements should we be using to determine API quality?
During the webinar we gave a preview of new data from the 2019 State of API Report, which will be published in January 2019. When it comes to how organizations are measuring quality, the top three responses were: performance, usability/developer experience, and uptime/availability. We also find that the top tools used to deliver quality APIs are: API Documentation Tools, API Functional Testing Tools, CI/CD Tools.
We will share more insights from the report in January, which will include a detail readout of perspectives on quality across the API lifecycle — from planning and design to testing and monitoring.
What is the difference between Swagger and OpenAPI?
The easiest way to understand the relationship of Swagger and the OpenAPI Specification is:
-
Swagger is a collection of open source, free, and pro tools, supported and developed by the team at SmartBear, which support the OpenAPI Specification.
-
OpenAPI is the name of the specification, which is supported by the Swagger tools and hundreds of other tools from different vendors outside of the Swagger tooling ecosystem.
The specification was formerly renamed in 2015 after the specification was donated to the Linux Foundation under the OpenAPI Initiative.
Learn more
Can I see what changes are made to an existing API? Is there a process for reviewing those processes before accepting?
SwaggerHub offers the ability to host and maintain multiple versions of an API definition. This means that you can have a published version, which is ready for development, and continue to work on the next version of the definition as your API evolves.
One of the ways that we see teams keep track of the changes that are being made to the API definition is with the commenting feature in the SwaggerHub editor. This lets you add feedback, request changes, and resolve issues right from within the editor.
When it comes to reviewing and merging changes to the API, teams can leverage the Compare & Merge functionality in SwaggerHub. This feature lets you compare the changes in your working version of the definition to the original published version. As an architect or manager, you can see a visual rending of what changes were made and can either choose to accept or reject the changes. If you have a set of rules that you know you want to enforce across your definitions and do not want to manually review and merge these updates, you can select them in rules in the API Standardization panel in your organization settings.
We work in a code first approach in a CI pipeline. Is it possible to have an automated test which generates our swagger from the code, submits it to your API and get a response indicating if it is valid or not according to the rules?
While we see a lot of teams and organizations using Swaggerhub through its web-interface, the API underneath the platform is equally as powerful. If you are generating OpenAPI dynamically through code annotations or frameworks, a simple POST call to the Registry API will allow the definition to be verified and stored as part of the larger internal catalog. This workflow makes not only submitting new definitions easy, but also pulling definitions down for testing or documentation a straight forward process as well. If you are interested in exploring our approach to ‘code-first’ in more detail, our recent webinar covered some of the workflows and plugins on offer.
Learn more
Interested in seeing the new API standardization feature in action? Join us for the special webinar replay on January 10th. Register Now