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 gen...
Forum Discussion
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:
Petstore3 example: https://petstore3.swagger.io/
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
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 .
ponelat can you please look into this issue ?
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
