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 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.
- Bold and Italic
- Lists (Unordered/Ordered)
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.
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 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.
Petstore_v3.yaml (26.3 KB)