Ask a Question

Swagger api to generate HTML from yaml

amitrao2344
New Contributor

Swagger api to generate HTML from yaml

I am trying to generate HTML from YAML file using . https://generator3.swagger.io/api/generate enpoint but if my yaml file has markdown text it does not seem to support and the html file which is generated does not parse markdown text .

How can I parse markdown text ?

6 REPLIES 6
ponelat
Staff

Re: Swagger api to generate HTML from yaml

Hi @amitrao2344 

 

It'll depend on which template you use, there are currently three: html, html2 and dynamic-html.

From what I can tell, html and html2 both support Markdown as you'd expect but dynamic-html doesn't appear to.

 

Here is a curl command to generate a html2 template using the petstore 3 example. In it you can see the markdown is rendered.

#!/usr/bin/env bash

curl -X POST "https://generator3.swagger.io/api/generate" -H "accept: application/octet-stream" -H "Content-Type: application/json" -d "{\"lang\":\"html2\",\"specURL\":\"https://petstore3.swagger.io/api/v3/openapi.json\",\"type\":\"CLIENT\",\"codegenVersion\":\"V3\",\"options\":{}}" -o output.zip

 

Screenshot:

ponelat_0-1632733293386.png

Petstore3 example: https://petstore3.swagger.io/

amitrao2344
New Contributor

Re: Swagger api to generate HTML from yaml

I am using html2 template and passing below yaml properties

 

description: |-

            Invalid request. There was an issue with the metric data provided in the request body. Possible error codes returned:

 

            Error Code                | Description          | Parameters Example

            --------------------------|----------------------|----------------------------

            BAD_REQUEST               | Cannot read request body for some reason. For instance, request contains fields with invalid format of integer, number, boolean, etc. | |

            INVALID_DATE_TIME_FORMAT  | The date time format of start time and/or end time fields is invalid. | |

            MISSING_REQUIRED_FIELDS   | One or more required fields for the metric were not provided or have nullable value. | "fields": \[ "deploymentUuid", "productShortCode", "measureUnit", "quantity", "startTime", "endTime"\]

            OUT_OF_BOUNDS_VALUE       | One or more fields have out of bounds value. | "fields": \[ {"fieldName": "quantity", "minValue": 1, "maxValue": 2147483647} \]

            MIN_LENGTH_REQUIRED       | One or more fields have the minimum field value length less than required. | "fields": \[ {"fieldName": "productShortCode", "minLength": 1}\]

            MAX_LENGTH_EXCEEDED       | One or more fields exceeded the maximum field value length. | "fields": \[ {"fieldName": "measureunit", "maxLength": 50}\]

            INVALID_DEPLOYMENT_UUID   | Deployment UUID should contain only alphanumeric characters and dashes. | |

            START_TIME_AFTER_END_TIME | Start time value should be before the end time value. | |

            REQUEST_EXPIRED           | The request reached the service more than 24 hours after the end time value. | |

            END_TIME_IN_FUTURE        | End time should not be in the future. | |

            MAX_TIME_PERIOD_DURATION_EXCEEDED | Time period between start and end time should not be greater than max time period duration. | "maxTimePeriodDurationInHours": 24

            CUSTOM_DATA_MAX_SIZE_EXCEEDED | Custom data field exceeded maximum number of key/value pairs. | "maxCustomDataSize": 10|

            CUSTOM_DATA_PROPERTY_MIN_LENGTH_REQUIRED | One or more custom data property key and/or value are nullable or have min length less than required. | "minKeyLength": 1, "minValueLength": 1

            CUSTOM_DATA_PROPERTY_MAX_LENGTH_EXCEEDED | One or more custom data property key and/or value have exceeded max length. | "maxKeyLength": 256, "maxValueLength": 256

 

But it shows up in converted HTML as below

amitrao2344_0-1632742550675.png

 

amitrao2344
New Contributor

Re: Swagger api to generate HTML from yaml

Markdown parsing works but not on all attributes of YAML file . 

I have attached sample YAML file which get transferred to corresponding HTML but does not parse Markdown text at line 106

but it get converted to HTML on line 30 . 

 

Note: I have attached yaml file with xml extension .

 

Can you please help .

 

amitrao2344
New Contributor

Re: Swagger api to generate HTML from yaml

@ponelat  can you please look into this issue ?

ponelat
Staff

Re: Swagger api to generate HTML from yaml

Hi @amitrao2344 

 

The html2 template does support Markdown in `description` fields, particularly the one in an operation. 

Although Markdown tables can be tricky to get right. In this case there are line breaks between the rows which cause it not to render a table. If you remove the lines between rows you should see better results.

 

openapi: 3.0.0
info:
  title: Test API
  version: 1.0.0

paths:
  /something:
    post:
      description: |-
        Invalid request. There was an issue with the metric data provided in the request body. Possible error codes returned:

        Error Code                | Description          | Parameters Example
        --------------------------|----------------------|----------------------------
        BAD_REQUEST               | Cannot read request body for some reason. For instance, request contains fields with invalid format of integer, number, boolean, etc. | |
        INVALID_DATE_TIME_FORMAT  | The date time format of start time and/or end time fields is invalid. | |
        MISSING_REQUIRED_FIELDS   | One or more required fields for the metric were not provided or have nullable value. | "fields": \[ "deploymentUuid", "productShortCode", "measureUnit", "quantity", "startTime", "endTime"\]
        OUT_OF_BOUNDS_VALUE       | One or more fields have out of bounds value. | "fields": \[ {"fieldName": "quantity", "minValue": 1, "maxValue": 2147483647} \]
        MIN_LENGTH_REQUIRED       | One or more fields have the minimum field value length less than required. | "fields": \[ {"fieldName": "productShortCode", "minLength": 1}\]
        MAX_LENGTH_EXCEEDED       | One or more fields exceeded the maximum field value length. | "fields": \[ {"fieldName": "measureunit", "maxLength": 50}\]
        INVALID_DEPLOYMENT_UUID   | Deployment UUID should contain only alphanumeric characters and dashes. | |
        START_TIME_AFTER_END_TIME | Start time value should be before the end time value. | |
        REQUEST_EXPIRED           | The request reached the service more than 24 hours after the end time value. | |
        END_TIME_IN_FUTURE        | End time should not be in the future. | |
        MAX_TIME_PERIOD_DURATION_EXCEEDED | Time period between start and end time should not be greater than max time period duration. | "maxTimePeriodDurationInHours": 24
        CUSTOM_DATA_MAX_SIZE_EXCEEDED | Custom data field exceeded maximum number of key/value pairs. | "maxCustomDataSize": 10|
        CUSTOM_DATA_PROPERTY_MIN_LENGTH_REQUIRED | One or more custom data property key and/or value are nullable or have min length less than required. | "minKeyLength": 1, "minValueLength": 1
        CUSTOM_DATA_PROPERTY_MAX_LENGTH_EXCEEDED | One or more custom data property key and/or value have exceeded max length. | "maxKeyLength": 256, "maxValueLength": 256

      tags:
      - Notification
      responses:
       default: 
         description: ok

 

ponelat_0-1632818676132.png

 

sonya_m
Community Manager

Re: Swagger api to generate HTML from yaml

Thank you ponelat!

 

Hi @amitrao2344 , looks like you replied straight to the email notification, this way your message won't reach the Community. Please make sure to reply inside the Community. Thank you!


Sonya Mihaljova
Community and Education Specialist

Did my reply answer your question? Give Kudos or Accept it as a Solution to help others. ⬇️⬇️⬇️
cancel
Showing results for 
Search instead for 
Did you mean: