add title, description to HTML output (#3860)

* add schema title, description to HTML output

* Include title, description in petstore sample (and HTML output)

modules/swagger-codegen/src/main/java/io/swagger/codegen/CodegenModel.java

@@ -18,7 +18,7 @@ public class CodegenModel {
     public CodegenModel parentModel;
     public List<CodegenModel> interfaceModels;
 
-    public String name, classname, description, classVarName, modelJson, dataType;
+    public String name, classname, title, description, classVarName, modelJson, dataType;
     public String classFilename; // store the class file name, mainly used for import
     public String unescapedDescription;
     public String discriminator;
@@ -80,6 +80,8 @@ public class CodegenModel {
             return false;
         if (classname != null ? !classname.equals(that.classname) : that.classname != null)
             return false;
+        if (title != null ? !title.equals(that.title) : that.title != null)
+            return false;
         if (description != null ? !description.equals(that.description) : that.description != null)
             return false;
         if (classVarName != null ? !classVarName.equals(that.classVarName) : that.classVarName != null)
@@ -143,6 +145,7 @@ public class CodegenModel {
         result = 31 * result + (interfaceModels != null ? interfaceModels.hashCode() : 0);
         result = 31 * result + (name != null ? name.hashCode() : 0);
         result = 31 * result + (classname != null ? classname.hashCode() : 0);
+        result = 31 * result + (title != null ? title.hashCode() : 0);
         result = 31 * result + (description != null ? description.hashCode() : 0);
         result = 31 * result + (classVarName != null ? classVarName.hashCode() : 0);
         result = 31 * result + (modelJson != null ? modelJson.hashCode() : 0);

modules/swagger-codegen/src/main/java/io/swagger/codegen/DefaultCodegen.java

@@ -1205,6 +1205,7 @@ public class DefaultCodegen {
         } else {
             m.name = name;
         }
+        m.title = escapeText(model.getTitle());
         m.description = escapeText(model.getDescription());
         m.unescapedDescription = model.getDescription();
         m.classname = toModelName(name);

modules/swagger-codegen/src/main/resources/htmlDocs/index.mustache

@@ -162,7 +162,8 @@
   {{#models}}
   {{#model}}
   <div class="model">
-    <h3 class="field-label"><a name="{{name}}">{{name}}</a> <a class="up" href="#__Models">Up</a></h3>
+    <h3 class="field-label"><a name="{{name}}">{{name}} - {{title}}</a> <a class="up" href="#__Models">Up</a></h3>
+    <div class='model-description'>{{description}}</div>
     <div class="field-items">
       {{#vars}}<div class="param">{{name}} {{^required}}(optional){{/required}}</div><div class="param-desc"><span class="param-type">{{^isPrimitiveType}}<a href="#{{complexType}}">{{datatype}}</a>{{/isPrimitiveType}}</span> {{description}} {{#dataFormat}}format: {{{dataFormat}}}{{/dataFormat}}</div>
       {{#isEnum}}

modules/swagger-codegen/src/test/resources/2_0/petstore.yaml

@@ -573,6 +573,8 @@ securityDefinitions:
     in: header
 definitions:
   Order:
+    title: Pet Order
+    description: An order for a pets from the pet store
     type: object
     properties:
       id:
@@ -600,6 +602,8 @@ definitions:
     xml:
       name: Order
   Category:
+    title: Pet catehgry
+    description: A category for a pet
     type: object
     properties:
       id:
@@ -610,6 +614,8 @@ definitions:
     xml:
       name: Category
   User:
+    title: a User
+    description: A User who is purchasing from the pet store
     type: object
     properties:
       id:
@@ -634,6 +640,8 @@ definitions:
     xml:
       name: User
   Tag:
+    title: Pet Tag
+    description: A tag for a pet
     type: object
     properties:
       id:
@@ -644,6 +652,8 @@ definitions:
     xml:
       name: Tag
   Pet:
+    title: a Pet
+    description: A pet for sale in the pet store
     type: object
     required:
       - name
@@ -681,6 +691,8 @@ definitions:
     xml:
       name: Pet
   ApiResponse:
+    title: An uploaded response
+    description: Describes the result of uploading an image resource
     type: object
     properties:
       code:

samples/html/index.html

@@ -1265,7 +1265,8 @@ font-style: italic;
   </ol>
 
   <div class="model">
-    <h3 class="field-label"><a name="ApiResponse">ApiResponse</a> <a class="up" href="#__Models">Up</a></h3>
+    <h3 class="field-label"><a name="ApiResponse">ApiResponse - An uploaded response</a> <a class="up" href="#__Models">Up</a></h3>
+    <div class='model-description'>Describes the result of uploading an image resource</div>
     <div class="field-items">
       <div class="param">code (optional)</div><div class="param-desc"><span class="param-type"><a href="#integer">Integer</a></span>  format: int32</div>
 <div class="param">type (optional)</div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span>  </div>
@@ -1273,14 +1274,16 @@ font-style: italic;
     </div>  <!-- field-items -->
   </div>
   <div class="model">
-    <h3 class="field-label"><a name="Category">Category</a> <a class="up" href="#__Models">Up</a></h3>
+    <h3 class="field-label"><a name="Category">Category - Pet catehory</a> <a class="up" href="#__Models">Up</a></h3>
+    <div class='model-description'>A category for a pet</div>
     <div class="field-items">
       <div class="param">id (optional)</div><div class="param-desc"><span class="param-type"><a href="#long">Long</a></span>  format: int64</div>
 <div class="param">name (optional)</div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span>  </div>
     </div>  <!-- field-items -->
   </div>
   <div class="model">
-    <h3 class="field-label"><a name="Order">Order</a> <a class="up" href="#__Models">Up</a></h3>
+    <h3 class="field-label"><a name="Order">Order - Pet Order</a> <a class="up" href="#__Models">Up</a></h3>
+    <div class='model-description'>An order for a pets from the pet store</div>
     <div class="field-items">
       <div class="param">id (optional)</div><div class="param-desc"><span class="param-type"><a href="#long">Long</a></span>  format: int64</div>
 <div class="param">petId (optional)</div><div class="param-desc"><span class="param-type"><a href="#long">Long</a></span>  format: int64</div>
@@ -1293,7 +1296,8 @@ font-style: italic;
     </div>  <!-- field-items -->
   </div>
   <div class="model">
-    <h3 class="field-label"><a name="Pet">Pet</a> <a class="up" href="#__Models">Up</a></h3>
+    <h3 class="field-label"><a name="Pet">Pet - a Pet</a> <a class="up" href="#__Models">Up</a></h3>
+    <div class='model-description'>A pet for sale in the pet store</div>
     <div class="field-items">
       <div class="param">id (optional)</div><div class="param-desc"><span class="param-type"><a href="#long">Long</a></span>  format: int64</div>
 <div class="param">category (optional)</div><div class="param-desc"><span class="param-type"><a href="#Category">Category</a></span>  </div>
@@ -1306,14 +1310,16 @@ font-style: italic;
     </div>  <!-- field-items -->
   </div>
   <div class="model">
-    <h3 class="field-label"><a name="Tag">Tag</a> <a class="up" href="#__Models">Up</a></h3>
+    <h3 class="field-label"><a name="Tag">Tag - Pet Tag</a> <a class="up" href="#__Models">Up</a></h3>
+    <div class='model-description'>A tag for a pet</div>
     <div class="field-items">
       <div class="param">id (optional)</div><div class="param-desc"><span class="param-type"><a href="#long">Long</a></span>  format: int64</div>
 <div class="param">name (optional)</div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span>  </div>
     </div>  <!-- field-items -->
   </div>
   <div class="model">
-    <h3 class="field-label"><a name="User">User</a> <a class="up" href="#__Models">Up</a></h3>
+    <h3 class="field-label"><a name="User">User - a User</a> <a class="up" href="#__Models">Up</a></h3>
+    <div class='model-description'>A User who is purchasing from the pet store</div>
     <div class="field-items">
       <div class="param">id (optional)</div><div class="param-desc"><span class="param-type"><a href="#long">Long</a></span>  format: int64</div>
 <div class="param">username (optional)</div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span>  </div>