Added strict rules and link to them from speccy

README.md

@@ -69,8 +69,6 @@ There are going to be different things people are interested in, so the [default
 
 There are [strict rules][rules-strict] which demand more contact details, "real" domains, a license, and requires tags have a description!
 
-There are also [wework rules][rules-wework], building things we consider important on top of the strict rules; keeping summaries short (so they fit into ReDoc navigation for example).
-
 #### Rules
 
 Rule actions from the [default rules][rules-default] will be used if no rules file is specified. Right now there are only the three bundled options, but supporting custom rules files via local path and URL is on the roadmap.

docs/_data/rules.yml

@@ -179,3 +179,51 @@ default:
     description: "markdown descriptions should not contain 'eval('"
     more: |
       Letting specification authors eval random code is proabably a Bad Idea™.
+
+strict:
+  - name: "contact-properties"
+    object: "contact"
+    description: "contact object should have name, url and email"
+    more: >
+        To make contact info the most useful, all of the options should be used. Including
+        a URL and an email address means the user has the most options to be able to get
+        in touch, maybe including a URL to your slack channel, or to a support portal,
+        and the email could be a team/company address to avoid having a single human as a
+        bottleneck.
+
+  - name: "license-url"
+    object: "license"
+    description: "license object should include url"
+    more: >
+        Having a license is generally a helpful idea, it lets potential users know how
+        they are allowed to leverage your API. Pick one from this [great list](https://opensource.org/licenses),
+        anywhere else, or make your own and link to it.
+
+  - name: "server-not-example.com"
+    object: "server"
+    description: "server url should not point at example.com"
+    more: >
+        You can do better than example.com! Set up at least a [mock server](http://openapi.tools/#mock),
+        maybe even a sandbox, or an actual implementation for users to play with.
+
+  - name: "tag-description"
+    object: "tag"
+    description: "tag object should have a description"
+    more: |
+        Adding descriptions to tags is a great way to explain business logic for the concept.
+
+        Often specifications will explain that there is a POST /foos and that creates a foo, and
+        there is a GET /foos which gets a bunch of foos, but nobody really explains what a Foo is
+        at any point.
+
+        ```
+        openapi: 3.0.1
+        tags:
+            - name: Foo
+              description: |
+                Multiple lines of text explain all about the concept of a foo in this system, how
+                they might related to other items, what sort of stage in the workflow are they
+                created, etc.
+
+                You can even put *markdown* in here!
+        ```

docs/_includes/rules-list.html

@@ -0,0 +1,29 @@
+<table class="table table-striped table-inverted">
+  <thead>
+    <tr>
+      <td>Name</td>
+      <td>OpenAPI Object</td>
+      <td>Description</td>
+    </tr>
+  </thead>
+  {% for rule in include.rules %}
+  <tr>
+    <td id="{{ rule.name }}">
+      <a href="#{{ rule.name }}">{{ rule.name }}</a>
+    </td>
+    <td>
+        {% if rule.object == "*" %}
+        <em>everything</em>
+        {% elsif rule.object == "openapi" %}
+        <a href="https://swagger.io/specification/#oasObject">{{ rule.object }}</a>
+        {% else %}
+        <a href="https://swagger.io/specification/#{{ rule.object }}Object">{{ rule.object }}</a>
+        {% endif %}
+    </td>
+    <td>{{ rule.description }}</td>
+  </tr>
+  <tr>
+    <td colspan=3>{{ rule.more | markdownify }}</td>
+  </tr>
+  {% endfor %}
+</table>

docs/rules.html

@@ -14,37 +14,16 @@ <h2 class="mb-5">Linter Rules</h2>
       are valid. They'll make your specs better than valid, they'll make them useful.</p>
 
     <div class="panel panel-default">
-      <h3 class="panel-title">Default</h3>
+      <h3 id="file-default" class="panel-title">Default</h3>
+      <div class="well">$ speccy lint openapi.yaml --rules=default</div>
+      {% include rules-list.html rules=site.data.rules.default %}
+    </div>
 
-      <table class="table table-striped table-inverted">
-        <thead>
-          <tr>
-            <td>Name</td>
-            <td>OpenAPI Object</td>
-            <td>Description</td>
-          </tr>
-        </thead>
-        {% for rule in site.data.rules.default %}
-        <tr>
-          <td id="{{ rule.name }}">
-            <a href="#{{ rule.name }}">{{ rule.name }}</a>
-          </td>
-          <td>
-              {% if rule.object == "*" %}
-              <em>everything</em>
-              {% elsif rule.object == "openapi" %}
-              <a href="https://swagger.io/specification/#oasObject">{{ rule.object }}</a>
-              {% else %}
-              <a href="https://swagger.io/specification/#{{ rule.object }}Object">{{ rule.object }}</a>
-              {% endif %}
-          </td>
-          <td>{{ rule.description }}</td>
-        </tr>
-        <tr>
-          <td colspan=3>{{ rule.more | markdownify }}</td>
-        </tr>
-        {% endfor %}
-      </table>
+    <div class="panel panel-default">
+      <h3 id="file-strict" class="panel-title">Strict</h3>
+      <div class="well">$ speccy lint openapi.yaml --rules=strict</div>
+      {% include rules-list.html rules=site.data.rules.strict %}
     </div>
+
   </div>
 </section>

lint.js

@@ -70,6 +70,8 @@ const formatLintResults = lintResults => {
         output += `
 ${colors.yellow + pointer} ${colors.cyan} R: ${rule.name} ${colors.white} D: ${rule.description}
 ${colors.reset + truncateLongMessages(error.message)}
+
+More information: https://speccy.io/rules/#${rule.name}
 `;
     });