Menu
I would like to format my Swagger API descriptions so that they are not simple paragraphs of text. Preferably, I'd like to add a small table to it.
I did not find an online reference about text formatting in Swagger descriptions. If I launch the Swagger Editor, and open the Instagram example (File \ Open Example \ Instagram.yaml), I see the the first description in the yaml file shows some formatting including a hyperlink and bounding box:
[registered your client](http://instagram.com/developer/register/) it's easy to start requesting data from Instagram. ``` https://api.instagram.com/v1/media/popular?client_id=CLIENT-ID ``` This looks like standard Markdown, but when I add a table markdown to the samples description, the editor presents an error:
|Col1|Col2| |------|------| |1|2| YAML Syntax Error End of the stream or a document separator is expected at line 36, column What formatting does Swagger 2.0 allow? Am I doing something wrong to render a table?
756
1 - Open the Properties dialog for your project, click the "Build" tab and ensure that "XML documentation file" is checked. This will produce a file containing all XML comments at build-time. At this point, any classes or methods that are NOT annotated with XML comments will trigger a build warning.
Format. An OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format.
To describe a parameter, you specify its name , location ( in ), data type (defined by either schema or content ) and other attributes, such as description or required . Here is an example: paths: /users/{userId}:
OpenAPI Specification (formerly Swagger Specification) is an API description format for REST APIs. An OpenAPI file allows you to describe your entire API, including: Available endpoints ( /users ) and operations on each endpoint ( GET /users , POST /users ) Operation parameters Input and output for each operation.
Markdown is supported in the Swagger Editor. Below is an example of using Markdown in an OpenAPI (Swagger) document:
swagger: '2.0' info: version: 0.0.0 title: Markdown description: | # Heading Text attributes _italic_, *italic*, __bold__, **bold**, `monospace`. Horizontal rule: --- Bullet list: * apples * oranges * pears Numbered list: 1. apples 2. oranges 3. pears A [link](http://example.com). An image:  Code block: ``` { "message": "Hello, world!" } ``` Tables: | Column1 | Column2 | | ------- | --------| | cell1 | cell2 | paths: /: get: responses: 200: description: OK You can copy and paste the above example to the Swagger Editor to see the output.
183
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With
