Swagger api to generate HTML from yaml

Question

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 ?

ponelat · Answer

Hi&nbsp;amitrao2344&nbsp;
&nbsp;
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.
&nbsp;
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
&nbsp;
Screenshot:

Petstore3 example:&nbsp;https://petstore3.swagger.io/

ponelat · Answer

Hi&nbsp;amitrao2344&nbsp;
&nbsp;
The html2 template does support Markdown in `description` fields, particularly the one in an operation.&nbsp;
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.
&nbsp;
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
&nbsp;

&nbsp;

amitrao2344 · Answer

I am using html2 template and passing below yaml properties&nbsp;description: |-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; Invalid request. There was an issue with the metric data provided in the request body. Possible error codes returned:&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; Error Code&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; | Description&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; | Parameters Example&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; --------------------------|----------------------|----------------------------&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; BAD_REQUEST&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; | Cannot read request body for some reason. For instance, request contains fields with invalid format of integer, number, boolean, etc. | |&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; INVALID_DATE_TIME_FORMAT&nbsp; | The date time format of start time and/or end time fields is invalid. | |&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; MISSING_REQUIRED_FIELDS&nbsp;&nbsp; | One or more required fields for the metric were not provided or have nullable value. | "fields": $$ "deploymentUuid", "productShortCode", "measureUnit", "quantity", "startTime", "endTime"$$&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; OUT_OF_BOUNDS_VALUE&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; | One or more fields have out of bounds value. | "fields": $$ {"fieldName": "quantity", "minValue": 1, "maxValue": 2147483647} $$&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; MIN_LENGTH_REQUIRED&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; | One or more fields have the minimum field value length less than required. | "fields": $$ {"fieldName": "productShortCode", "minLength": 1}$$&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; MAX_LENGTH_EXCEEDED&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; | One or more fields exceeded the maximum field value length. | "fields": $$ {"fieldName": "measureunit", "maxLength": 50}$$&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; INVALID_DEPLOYMENT_UUID&nbsp;&nbsp; | Deployment UUID should contain only alphanumeric characters and dashes. | |&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; START_TIME_AFTER_END_TIME | Start time value should be before the end time value. | |&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; REQUEST_EXPIRED&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; | The request reached the service more than 24 hours after the end time value. | |&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; END_TIME_IN_FUTURE&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; | End time should not be in the future. | |&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; MAX_TIME_PERIOD_DURATION_EXCEEDED | Time period between start and end time should not be greater than max time period duration. | "maxTimePeriodDurationInHours": 24&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &nbsp;CUSTOM_DATA_MAX_SIZE_EXCEEDED | Custom data field exceeded maximum number of key/value pairs. | "maxCustomDataSize": 10|&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 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&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; CUSTOM_DATA_PROPERTY_MAX_LENGTH_EXCEEDED | One or more custom data property key and/or value have exceeded max length. | "maxKeyLength": 256, "maxValueLength": 256&nbsp;But it shows up in converted HTML as below&nbsp;

amitrao2344 · Answer

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 .

Sampleyaml.xml20 KB

amitrao2344 · Answer

ponelat&nbsp; can you please look into this issue ?

Forum Discussion

Swagger api to generate HTML from yaml

Related Content

Generate HTML reports - Command line.

Swagger codegen/Swagger editor don't want to generate example

ApiModelProperty definition and generation of static html documentation

Generate JSON Schemas

How to suppress requestBody generation in OpenAPI spec using swagger-maven-plugin

Recent Discussions

Bootstrapped servlet returns empty JSON as of 2.2.24

Python 3.6 client support

I want to add variable in swagger like postman

Endpoint Expansion

Mixed-Type Arrays with java swagger-annotations 2.0.3.