webMethods API Portal tutorial

Being a marketplace for selling your APIs to the end users, webMethods API Portal supports API Portal supports rich text inputs for the descriptions fields of an API/ Resource/ Method.  Business users who are not familiar with HTML writing can use a simpler markdown syntaxes to beautify the API documentation easily.

Markdown

Markdown is a lightweight markup language with plain text formatting syntax. It is designed so that it can be converted to HTML and many other formats. For examples inorder to generate a headers of different size:

There are plenty of things that you could do with markdown to beautify API documentation. Below one is a subset of HTML structures that markdown can help you to generate.

1. Paragraphs
2. Headings
3. Blockquotes
4. Bold and Italic
5. Strikethrough
6. Emojis
7. Lists (Unordered/Ordered)
8. Links
9. Images
10. Tables

For the complete list of supported things you can check https://spec.commonmark.org/0.27/. There is also a online tool (https://markdown-it.github.io/) which would generate instant HTML from the Markdown provided.

Specification supports

Open API 3.0

Throughout the Open API 3.0 specification description fields are noted as supporting CommonMark markdown formatting. Open API specification as such recommend to use CommonMark 0.27 version for its rich text inputs. 

Swagger 2.0

Swagger also support rich text inputs for description fields. Swagger specification supports Github Flavoured Mardown(GFM) specification for its markdown support.

webMethods API Portal

For webMethods API Portal we follow showdown's markdown syntax for rendering rich texts. For a demo we created a sample petstore specification based OpenAPI 3.0 and imported in webMethods API Portal and its looks as below.

1920×4419 362 KB

Petstore.png1920×4419 241 KB

Petstore_v3.yaml (26.3 KB)

Further read:
To learn how to customize and get the most out of webMethods API Portal check out the listed tutorials here: webMethods API Portal tutorials

Watch this short demo on how to customize webMethods API Portal: webMethods API Portal Customization