Openapi Description Markdown



You can customize several metadata configurations in your FastAPI application.

Installation pip install open-api-schemas-to-markdown Usage. The package provides a command line tool. $ oa-to-md -h usage: oa-to-md -h inputfilepath outputfilepath locale positional arguments: inputfilepath The OpenAPI 3 YAML filepath outputfilepath The desired output filepath of the Markdown file locale Locale to use when generating the Markdown file. A curated list of amazingly awesome Elixir libraries, resources, and shiny things inspired by awesome-php. If you think a package should be added, please add a đź‘Ť (:+1:) at the according issue or create a new one. There are other sites with curated lists of elixir packages which you can have a.

OpenAPI can be intimidating when viewed as a single file. If you view an OpenAPI file that was generated by a code annotation tool, they are often optimizing each line break and stuff the entire definition into a single line. This is not usable by a human. Even when 'pretty printed' the output can be many thousands of lines and daunting to edit.

Title, description, and version¶

You can set the:

  • Title: used as your API's title/name, in OpenAPI and the automatic API docs UIs.
  • Description: the description of your API, in OpenAPI and the automatic API docs UIs.
  • Version: the version of your API, e.g. v2 or 2.5.0.
    • Useful for example if you had a previous version of the application, also using OpenAPI.

To set them, use the parameters title, description, and version:

With this configuration, the automatic API docs would look like:

Metadata for tags¶

You can also add additional metadata for the different tags used to group your path operations with the parameter openapi_tags.

It takes a list containing one dictionary for each tag.

Each dictionary can contain:

  • name (required): a str with the same tag name you use in the tags parameter in your path operations and APIRouters.
  • description: a str with a short description for the tag. It can have Markdown and will be shown in the docs UI.
  • externalDocs: a dict describing external documentation with:
    • description: a str with a short description for the external docs.
    • url (required): a str with the URL for the external documentation.

Create metadata for tags¶

Let's try that in an example with tags for users and items.

Create metadata for your tags and pass it to the openapi_tags parameter:

Notice that you can use Markdown inside of the descriptions, for example 'login' will be shown in bold (login) and 'fancy' will be shown in italics (fancy).

Tip

You don't have to add metadata for all the tags that you use.

Use your tags¶

Use the tags parameter with your path operations (and APIRouters) to assign them to different tags:

Info

Read more about tags in Path Operation Configuration.

Check the docs¶

Now, if you check the docs, they will show all the additional metadata:

Order of tags¶

The order of each tag metadata dictionary also defines the order shown in the docs UI.

For example, even though users would go after items in alphabetical order, it is shown before them, because we added their metadata as the first dictionary in the list.

Description

OpenAPI URL¶

By default, the OpenAPI schema is served at /openapi.json.

But you can configure it with the parameter openapi_url.

For example, to set it to be served at /api/v1/openapi.json:

If you want to disable the OpenAPI schema completely you can set openapi_url=None, that will also disable the documentation user interfaces that use it.

Docs URLs¶

You can configure the two documentation user interfaces included:

  • Swagger UI: served at /docs.
    • You can set its URL with the parameter docs_url.
    • You can disable it by setting docs_url=None.
  • ReDoc: served at /redoc.
    • You can set its URL with the parameter redoc_url.
    • You can disable it by setting redoc_url=None.

For example, to set Swagger UI to be served at /documentation and disable ReDoc:

Looking for SwaggerHub On-Premise release notes? See here.

This page contains the release notes for features and updates to SwaggerHub SaaS platform.

April 20, 2021

  • Enforce private visibility for organization-owned APIs. Organizations on Enterprise plans have a new option, Allow Designers to make APIs & Domains Public. If this option is disabled, all new APIs, domains, and versions in this organizations will be created as private, and only organization owners can make them public.

    Note:This option does not change the visibility of existing APIs and domains.

  • Increased catalog page size. My Hub, organization catalog pages, and search results now show 25 items per page instead of 10 items.

  • Help menu changes. The help menu has been simplified. Also, we added the Get Feedback link that the logged in users can use to sign up for SwaggerHub UX research.

  • Updated Swagger UI to v. 3.46.0 and Swagger Editor to v. 3.15.11.

March 30, 2021

Overall improvements:

  • Catalog pages and the editor now display long API names and domain names in full.

  • New code generators for Java:

    • OpenAPI 3.0: jaxrs-cxf, jaxrs-spec

    • OpenAPI 2.0: java-pkmst

  • Updated Swagger Codegen to v. 3.0.25 for OpenAPI 3.0 and v. 2.4.19 for OpenAPI 2.0.

  • Updated Swagger UI to v. 3.45.0 and Swagger Editor to v. 3.15.9.

Registry API updates:

  • The 'execute integration' operation now returns HTTP status 409 instead of 400 if the integration is disabled.

March 15, 2021

Overall improvements:

  • Custom standardization rules can now be deleted.

  • Updated Swagger UI to v. 3.43.0 and Swagger Editor to v 3.15.6.

Registry API updates:

  • A new operation to partially update integration settings:

February 24, 2021

Overall improvements:

  • OpenAPI 3.0 support in the Amazon API Gateway Lambda Sync integration.

  • Changes in the search syntax:

    • To improve search performance, words less than 3 characters long (such as a, an, to, and others) are now ignored.

    • All characters, except for + - |, are now searchable. For example, the search string /users/{id} is now matched exactly, whereas previously it was converted to users id (that is, users AND id).

Registry API updates:

  • Integration-related operations now support the remaining integrations: Amazon API Gateway Lambda Sync, Apigee Edge, Azure API Management, and IBM API Connect.

  • The 'create integration' operation now returns the ID of the created integration, which you can then use to run that integration.

February 9, 2021

Overall improvements:

  • Updated Swagger UI to v. 3.41.1, which includes the following enhancements:

    • Generating examples for YAML media types.

    • Grouping and sorting parameters by location (in attribute).

  • Updated Swagger Editor to v. 3.15.4.

Registry API updates:

  • New operations to manage integrations:

    • Get all integrations configured for a specific API version.

    • Get integration settings.

    • Update integration settings.

    • Run an integration.

    • Delete an integration.

  • All integration-related operations now also support the Amazon API Gateway integration.

January 26, 2021

  • Updated Swagger Codegen to v. 3.0.24 for OpenAPI 3.0 and v. 2.4.18 for OpenAPI 2.0.

January 13, 2021

  • Interactive API docs now remember the selected server after page refresh.

  • Registry API updates:

    • New GET /projects operation to get all projects to which a user has access.

    • POST /apis/{owner}/{api} and POST /domains/{owner}/{domain} now detect the OpenAPI version (3.0 or 2.0) of uploaded files automatically. Previously, OpenAPI 3.0 uploads required the use of the ?oas=3.0.0 query parameter - this is no longer needed. The oas parameter has been removed.

  • Updated Swagger UI to 3.38.0, which adds support for the OpenID Connect Discovery (OIDC) security scheme.

  • Updated Swagger Editor to v. 3.14.8.

2020 release notes

December 9, 2020

  • Organization owners can delete unused credit cards from payment methods.

  • Registry API updates:

    • New operations to fork APIs and domains:

    • Operations that download API definitions have a new flatten parameter that affects the structure of resolved YAML and JSON. Flattening replaces all inline complex schemas with named entries in the components/schemas or definitions section.

November 24, 2020

  • Catalog pages and search results can now be sorted by the document title (info.title).

  • Parameter definitions in domains now display x- extensions and the pattern, min*, and max* attributes.

  • Registry API updates:

    • New operations to rename APIs and domains:

    • The sort parameter of search operations supports a new value, TITLE.

  • Updated Swagger Editor to v. 3.14.6 and Swagger UI to v. 3.36.2.

November 9, 2020

  • New Registry API operations to create and manage projects in organizations.

  • Updated Swagger UI to v. 3.36.1, which includes the following improvements:

    • The minProperties and maxProperties attributes for object schemas are displayed.

    • x- extensions in responses are displayed.

  • Updated Swagger Editor to v. 3.14.5.

  • Updated Swagger Codegen to v. 3.0.23 for OpenAPI 3.0 and v. 2.4.17 for OpenAPI 2.0.

November 2, 2020

Enhanced search functionality:

  • Faster search results. We’ve improved search performance so you will see results faster.

  • Full-text search. SwaggerHub now also searches the entire YAML contents of API definitions and domains. For example, you can search for definitions that contain specific paths, parameters, or schemas.

  • Partial word search. For example, book will find books, ebook, booking, and so on.

  • Search using boolean operators. You can combine the search terms using AND, OR, NOT. For example, upload OR submit will find definitions containing either word.

  • New Best Match sorting shows the search results ranked by relevance. This is now the default sort order for search results.

See Searching SwaggerHub for more information.

October 27, 2020

  • New Registry API operations to get and set the visibility (public or private) of APIs and domains:

  • Updated Swagger Codegen to v. 3.0.22 for OpenAPI 3.0 and v. 2.4.16 for OpenAPI 2.0.

October 12, 2020

  • Designers and consumers can now see their role on the organization catalog page:

  • Registry API updates:

    • The 'create integration' operation (POST /apis/{owner}/{api}/{version}/integrations) supports additional integrations: webhooks and API Auto Mocking.

    • The version parameter of the 'create or update a domain' operation (POST /domains/{owner}/{domain}) is now optional. This aligns with the corresponding API-specific operation (POST /apis/{owner}/{api}).

    • Registry API now validates request bodies sent with POST, PUT, and PATCH requests to make sure they conform to the OpenAPI definition. This includes making sure that the required fields are present, all values have the correct data types, and so on. As a result, requests that previously worked without required fields in the body will no longer work and will need to be updated.

Api

September 28, 2020

Registry API improvements:

  • The 'create integration' operation (POST /apis/{owner}/{api}/{version}/integrations) supports additional integrations: Bitbucket Cloud, Bitbucket Server, and Azure DevOps Services.

  • The enabled field of integration configuration is now optional and defaults to true.

Openapi Description Markdown Definition

September 15, 2020

  • In APIs that use mocking, the mock is now automatically created for new versions of the API.

  • The Export > Download API > YAML Resolved and JSON Resolved commands now download the actual YAML or JSON file instead of a ZIP archive.

  • Interactive API documentation now displays vendor extensions (x- fields) in operations, parameters, and schemas.

  • New option for 'try it out' requests: Credentials in CORS requests. This option becomes available when routing requests via browser and corresponds to Swagger UI’s withCredentials option. Set this option based on how CORS is configured on the API server:

    Enable this option if the API server sends back the origin header, such as Access-Control-Allow-Origin: https://app.swaggerhub.com.

    Disable this option if the API server sends the Access-Control-Allow-Origin: * response header. Note: If this option is disabled, CORS requests will not include browser cookies or the Authorization header.

  • New Registry API operation to add GitHub and GitLab integrations to API definitions:

August 31, 2020

  • Webhooks are now carried over when you create a new version of an API.

  • New Registry API operations:

    • add/create a new version of an API or domain:

    • get API standardization errors:

August 17, 2020

  • Added the Go and TypeScript Fetch client generators for OpenAPI 3.0.

  • Updated Swagger Codegen to v. 3.0.21 for OpenAPI 3.0 and v. 2.4.15 for OpenAPI 2.0.

  • Added Registry API operations to read, add, and manage comments in API definitions and domains.

    The following operations have been deprecated in favor of the new ones:

August 4, 2020

  • Integration with self-hosted GitHub Enterprise servers. Your GitHub Enterprise instance must be accessible from the public Internet and allow connections from our IP addresses.

    Note:GitHub Enterprise integration is available for organizations on the Team and Enterprise plans.

  • Catalog pages (My Hub, organization pages, and others) now have the 'delete' button so that you can quickly delete APIs and domains you no longer need.

  • Improved syntax validation for domains.

  • Updated Swagger Editor to v. 3.11.7.

  • Updated Swagger UI to v. 3.30.0, which includes the following improvements:

    • Syntax highlighting in request bodies, response bodies, and cURL commands.

    • An option to send or omit optional form fields with empty values. (OpenAPI 3.0)

    • Validating the presence of required form fields before sending requests. (OpenAPI 3.0)

  • Interactive API documentation now also displays the pattern, min*, and max* attributes for operation parameters.

July 20, 2020

  • Pulling API definitions from source control. If you store your OpenAPI definitions in a Git repository, you can now pull them from the repository into SwaggerHub. To be able to do this, you need to configure a source control integration in SwaggerHub with the target file set to an unresolved YAML or JSON definition. Such an integration will allow bi-directional synchronization (both push and pull) between SwaggerHub and the Git repository. For details, see Syncing OpenAPI Definitions Between Source Control and SwaggerHub.

    Note:Pulling from source control is only available for organizations on the Enterprise plan.

  • Added C++ (Pistache, Restbed) server generators for OpenAPI 2.0.

  • Updated Swagger Codegen to v. 3.0.20 for OpenAPI 3.0 and v. 2.4.14 for OpenAPI 2.0.

  • Updated Swagger Editor to v. 3.11.6 which includes new syntax validations:

    • Check for path parameters that are defined in the parameters list but not included in the path itself (for example, if a path is defined as /users instead of /users/{id}).

    • Validate component names in OpenAPI 3.0 definitions. Component names can contain only A-Z a-z 0-9 - . _

    • Validate that a schema’s default value is present in the enum.

    • Validate schemas in the components/schemas section in OpenAPI 3.0 definitions.

    • Validate that min* values are less than or equal to the corresponding max* values in OpenAPI 3.0 definitions.

    • Validate that OpenAPI 3.0 parameter references, header references, and requestBody schema references point to the correct component types.

  • Updated Swagger UI to v. 3.28.0, which includes the following improvements:

    • A button to copy 'try it out' response body to clipboard.

    • 'Try it out' support for uploading array of files in multipart/* requests in OpenAPI 3.0 definitions.

    • Display the nullable attribute for object schemas.

    • Hide readOnly properties in the Model/Schema view of requests, and hide writeOnly properties in the Model/Schema view of responses.

July 6, 2020

The Azure API Management integration has the new API URL Suffix option to set the base path of your API gateway in Azure, such as https://{instance}.azure-api.net/myApi.

July 1, 2020

SwaggerHub IP addresses have been changed. If you have firewall rules that allow traffic from our IP addresses, make sure to update those rules.

June 24, 2020

Introducing SwaggerHub CLI – a free command-line tool to interact with SwaggerHub Registry API. You can use it in your CI/CD pipelines to create and update APIs, download API definitions, publish and unpublish API versions, and set the default API version among other things.

June 8, 2020

  • Visual Editor improvements:

    • Add new schemas (models) by clicking the button next to the schema list in the Navigation:

    • Delete operations and models from the Navigation panel.

  • Download resolved definitions via SwaggerHub Registry API by adding the ?resolved=true query parameter to the URL of your API’s YAML/JSON file.

    Resolved YAML:

    Resolved JSON:

  • Updated Swagger Editor to v. 3.9.0, which improves OpenAPI syntax validation:

    • Warn about ignored header parameters in OpenAPI 3.0 definitions and suggest how to define those headers instead.

    • Warn about unused security schemes.

    • Show an error if minItems > maxItems.

    • Validate schemas in OpenAPI 3.0 response components.

  • Updated Swagger UI to v. 3.25.4, which includes the following improvements:

    • Display parameter format in OpenAPI 3.0 definitions.

    • Support for Basic authentication with an empty password.

May 26, 2020

  • Added the Rust server generator for OpenAPI 2.0.

May 12, 2020

Pushing to source control has become easier. The SwaggerHub editor now provides the Push button to trigger source control integrations, which works separately from the Save action. This way, you can save the API definition changes incrementally and only push to the source control repository when ready to do so.

You can also provide a custom commit message when pushing the changes.

Note:Non-source control integrations, such as API Auto Mocking and Webhooks, are still triggered on save.

April 29, 2020

  • Improved syntax validation for OpenAPI 3.0 domains.

April 14, 2020

  • Support for OpenAPI 3.0.3: you can import API definitions that use openapi: 3.0.3.

  • AWS Lambda integration now supports newer versions of Node.js and Python. You can choose from:

    • Node.js 12
    • Node.js 10
    • Python 3.8
    • Python 3.7
    • Python 3.6
    • Python 2.7
    Note: Node.js 4.3 was removed because it is no longer supported by Lambda. If you used this version, you will need to update your integrations to a newer version of Node.js.

  • New supported regions in AWS integrations: ap-east-1 and me-south-1.

  • Swagger Codegen was updated to v. 3.0.19 for OpenAPI 3.0 definitions and v. 2.4.13 for OpenAPI 2.0 definitions.

March 30, 2020

  • Commenting permissions for Consumers. Organizations have the new option to give Consumers and Designers permissions to comment on the organization’s APIs and domains. This allows Consumers to offer feedback on the API design and ask implementation questions as they consume the API.

  • New Registry API operations to get and set the default version, publish and unpublish versions, get the published status.

  • The Basic Sync mode of source control integrations now allows custom branch names.

  • When you create a new version and choose to copy source control integrations, the branch for the copied integrations will be set to swaggerhub-<API-name>-<version>. You can change the branch name later if you want.

March 16, 2020

  • SwaggerHub IP addresses have been changed. If you have firewall rules that allow traffic from our IP addresses, make sure to update those rules.

  • Source control integrations are now carried over when you create a new version of an API.

March 9, 2020

  • Added the Swift 5 client code generator for OpenAPI 3.0.

  • Updated Swagger Codegen to v. 3.0.18 for OpenAPI 3.0 and v. 2.4.12 for OpenAPI 2.0.

  • Improved browser tab titles for various SwaggerHub pages. The titles now better indicate what is in each tab, making it easier to work with multiple SwaggerHub pages open at the same time.

February 6, 2020

  • Updated Swagger Editor to v. 3.8.0, which adds a new validation for 'enum values should conform to their schema’ss type'.

  • Updated Swagger UI to v. 3.25.0, which adds support for the x-tokenName extension in OpenAPI 3.0 definitions.

  • Updated dialog box styles.

January 23, 2020

  • Single sign-on support for organizations with multiple email domains.

  • Extended Designer permissions:

    • Designers can transfer APIs and domains to organizations where they have Create permissions.

    • Designers can add APIs and domains to projects.

  • New Project option in Create, Import, Fork, and Save As dialogs allows adding newly created definitions to an existing project.

  • The Transfer Ownership command in the editor was replaced with Manage Owner & Project which also allows adding definitions to projects.

  • Catalog pages and the Info panel now also display the title (info.title) of APIs and domains.

January 8, 2020

New code generators for OpenAPI 3.0:

  • Node.js server
  • Python client

2019 release notes

December 9, 2019

  • See who created an API or domain. The API/domain Info panel now shows the username of the person who created the current version of the API or domain.

    Note:The 'created by' information is only available for versions created after November 26, 2019.

  • API listing pages now show both the error and warning badges for APIs that have both types of standardization issues.

  • Updated Swagger Editor to v. 3.7.1, which improves OpenAPI syntax validation:

    • Added a check for mismatching letter case in path parameter names and the corresponding path segments (for example, if the path is /users/{ID}, but the parameter name is id).

    • Improved the warning about sibling keywords alongside $ref to suggest possible solutions.

  • Updated Swagger UI to v. 3.24.3.

November 26, 2019

  • Custom standardization rules. Organization owners can add custom rules to validate API definitions for compliance with the company’s design guidelines.

  • New code generators:

    • Go server for OpenAPI 3.0

    • Swift 5 client for OpenAPI 2.0

  • New search keywords, standardization:critical and standardization:warning, let you find APIs with standardization errors and warnings, respectively.

  • Updated Swagger Codegen to v. 3.0.14 for OpenAPI 3.0 and v. 2.4.10 for OpenAPI 2.0.

October 31, 2019

  • Updated Swagger Codegen to v. 3.0.13 for OpenAPI 3.0 and v. 2.4.9 for OpenAPI 2.0.

  • Minor UI updates.

October 16, 2019

  • Updated application colors.

  • The Navigation panel in Code Editor is now resizable.

September 30, 2019

  • Support for permalinks to API models. API model permalinks have the #/MODEL_NAME format, for example:

  • SwaggerHub sidebar now provides quick access to user settings, organization settings, and project settings via the button.

  • Code Editor and Visual Editor now remember their editor and UI panel widths independently.

  • Updated Swagger Editor to v. 3.6.36.

  • Updated Swagger UI to v. 3.23.11.

September 16, 2019

  • OpenAPI 3.0 parameters with content are now displayed and can be used in 'try it out'.

  • Updated Swagger Editor to v. 3.6.34.

  • Updated Swagger UI to v. 3.23.8.

September 2, 2019

  • UI tweaks in Visual Editor.

  • Updated Swagger Editor to v. 3.6.33, which improves validation of tag uniqueness.

  • Updated Swagger UI to v. 3.23.5.

  • Updated Swagger Codegen to v. 3.0.11 for OpenAPI 3.0 and v. 2.4.8 for OpenAPI 2.0.

August 22, 2019

  • Support for multiple examples in parameters, request bodies, and responses in OpenAPI 3.0 definitions and domains.

  • Updated Swagger UI to v. 3.23.3.

  • Updated Swagger Editor to v. 3.6.31.

August 7, 2019

  • Integration with self-hosted Bitbucket Servers.

  • Visual Editor now lets you edit API servers and server variables in OpenAPI 3.0 definitions.

July 22, 2019

  • Support for OpenAPI 3.0.2: you can import API definitions that use openapi: 3.0.2.

  • Organization members can now see a list of organization owners on the My Organizations screen.

  • Updated Swagger Codegen to v. 3.0.10 for OpenAPI 3.0 definitions and v. 2.4.7 for OpenAPI 2.0.

July 15, 2019

  • Increased the 'try it out' timeout to 30 seconds for requests routed via SwaggerHub proxy.

Openapi

July 9, 2019

  • New OpenAPI 3.0 code generators: ASP.NET Core server, C# client, Python Flask server.

  • OpenAPI 3.0 support in Apigee Edge integration.

  • Azure API Management integration can now be authorized via Azure AD. The new approach replaces previously used 'SharedAccessSignature' tokens that had to be re-generated manually every 30 days.

    Note:Users who configured this integration for OpenAPI 2.0 APIs before July 9, 2019 need to re-authenticate the integration by clicking the Sign in with Microsoft button in the integration settings. Old tokens will continue to work until they expire.

  • Support for auto-provisioning GitLab integration via the SwaggerHub Maven plugin.

  • Updated Swagger Codegen to v. 3.0.9 for OpenAPI 3.0 definitions and 2.4.6 for OpenAPI 2.0.

  • Added a link to this changelog to the menu.

June 24, 2019

  • Single sign-on is now available to organizations on the Enterprise plan. SwaggerHub SaaS currently supports the following identity providers:

    • Azure Active Directory (Azure AD)
    • Okta
    • OneLogin
    • PingFederate

    Please contact your account manager if you are interested in enabling single sign-on for your organization.

  • Updated Swagger Editor to v. 3.6.30.

  • Updated Swagger UI to v. 3.22.3.

June 10, 2019

  • Visual Editor now lets you manage tags and edit tag metadata.

  • Updated Swagger Editor to v. 3.6.29 and Swagger UI to v. 3.22.2.

May 29, 2019

  • Visual Editor opens with the Navigation panel opened by default.

  • Updated Swagger Editor to v. 3.6.28, which improves error reporting for OpenAPI syntax errors.

May 15, 2019

  • OpenAPI 3.0 support in the Azure API Management integration.

  • New supported regions in the Amazon API Gateway Lambda Sync integration: us-east-2, eu-west-2, eu-west-3, eu-north-1, ap-south-1, cn-north-1, cn-northwest-1, ca-central-1.

  • Visual Editor now supports editing model descriptions.

  • Interactive Docs have a new option to ignore SSL certificate errors for 'try it out' requests routed via SwaggerHub proxy. This allows sending requests to servers that use self-signed SSL certificates. The option can be found at the bottom of the Interactive Docs in the Editor.

  • Updated Swagger Codegen to v. 3.0.8 for OpenAPI 3.0 and v. 2.4.5 for OpenAPI 2.0.

  • Updated Swagger UI to v. 3.22.1.

April 29, 2019

  • Visual Editor has new API Info fields for externalDocs.

  • Organization owners can see member email addresses in the member list.

  • Account Settings have been rearranged into vertical tabs.

  • Support for auto-provisioning Azure DevOps Service integration via the SwaggerHub Maven plugin.

Openapi Description Markdown

April 15, 2019

  • Visual Editor for API info and operation metadata. Use the Visual Editor to easily update operation summaries, descriptions, tags, and API information without having to remember the corresponding OpenAPI YAML markup. You can switch between the Code Editor and Visual Editor by using the sidebar buttons in the SwaggerHub editor.

  • Integration with Azure DevOps Services (formerly Visual Studio Team Services, or VSTS). Use it to push your API definition or the generated client/server code to a specific repository in Azure DevOps Services. The integration is available for both OpenAPI 2.0 and OpenAPI 3.0 definitions.

  • Added safety measures to protect organization owners from accidentally deleting organizations with an active plan. Now, an organization's plan must be canceled before the organization can be deleted.

  • Updated Swagger Editor to 3.6.26, which improves autocompletion for OAS3 schema components.

  • Updated Swagger UI to 3.22.0, which includes support for GFM table syntax in OpenAPI 3.0 descriptions and improved styles for <pre> code blocks.

April 1, 2019

  • Docs Branding. Organizations can upload a logo for use in consumer-facing documentation. This custom logo will be displayed in all API docs and domain docs of the organization.

  • Support for auto-provisioning Bitbucket integration via the SwaggerHub Maven plugin.

  • Updated Swagger Codegen to v. 3.0.7 for OpenAPI 3.0 and v. 2.4.4 for OpenAPI 2.0.

  • Updated Swagger Editor to v. 3.6.25.

March 19, 2019

  • Lazy loading of external $refs. SwaggerHub editor and interactive documentation now load external $refs (such as domain references) only when they are required to render a specific operation. Loading happens, for example, when a user expands an operation in the API docs. This reduces the API load time and improves performance.

    Note:Lazy loading affects how domain errors are surfaced in the API editor. Learn more.

  • Domains display additional OpenAPI 3.0 components: request bodies, headers, examples, links, and callbacks.

  • Support for auto-provisioning GitHub integration via the SwaggerHub Maven plugin.

  • Updated Swagger Editor to v. 3.6.24.

  • Updated Swagger UI to v. 3.21.0, which includes styling improvements and support for x-www-form-urlencoded request bodies without explicitly-defined properties.

March 4, 2019

  • OpenAPI 3.0 support for Domains. OAS3 Domains can include additional component types – request bodies, response headers, examples, links, and callbacks.

  • Updated Swagger Editor to v. 3.6.21, which improves OpenAPI 3.0 syntax validation.

  • Updated Swagger UI to v. 3.20.7.

  • Updated Swagger Codegen to v. 3.0.5 and 2.4.2.

February 19, 2019

  • OpenAPI 3.0 support in the Amazon API Gateway integration.

  • Request duration in 'try it out' results.

  • Updated Swagger UI to v. 3.20.6.

February 5, 2019

  • Improved domain syntax validation.

  • Moved documentation generators to a separate Documentation submenu in the Export menu.

  • Added the View Documentation button in the editor to open the API documentation in a new browser tab.

  • Rearranged organization settings pages into vertical tabs.

  • Updated Swagger Editor to v. 3.6.20 and Swagger UI to v. 3.20.5, which include the following improvements:

    • Displaying request body descriptions for OpenAPI 3.0 form data requests.

    • Markdown support in OpenAPI 3.0 form field descriptions.

    • Markdown support in response header descriptions.

January 21, 2019

Swagger Multiline Description

  • SwaggerHub API improvement: Added the oas parameter to POST /apis/{owner}/{api} to specify the OpenAPI Specification version used in the uploaded definition.

  • Updated Swagger Editor to v. 3.6.19.

  • Updated Swagger UI to v. 3.20.4.

  • Updated OAS3 Swagger Codegen to v. 3.0.4.

January 8, 2019

Openapi Description Markdown Software

  • Branding updates.

  • Added 8 new regions to the AWS API Gateway integration: us-east-2, ap-south-1, ap-northeast-3, ca-central-1, eu-west-2, eu-west-3, cn-north-1, cn-northwest-1.

  • Added new OpenAPI 2.0 code generators: php-symfony (server), skala-gatling and typescript-inversify (clients).

  • Updated Swagger Editor to 3.6.17.

  • Updated Swagger UI to 3.20.2, which adds rendering of OpenAPI 3.0 server descriptions.