Create DOCS_PLAN.md

Fixes #3633 - PrimitiveModel titles

DOCS_PLAN.md

@@ -0,0 +1,54 @@
+# Swagger OSS Documentation Plan
+
+Notes: 
+- I came across GitBook recently, and it looks like a great way to host documentation. Example: https://jonas.github.io/tig/, https://codiechanel.gitbooks.io/gitbook-demo/content/
+
+### Swagger-UI
+
+##### Usage (12h)
+- Downloading the project via npm, git submodules, packagist, unkpg cdn
+- How to integrate with generic JS, React
+- How to use Docker image (basic + Docker Compose)
+- Configuration options and their individual docs
+- Instance method (`initOAuth`, etc) documentation
+
+##### Customization (16h)
+- Plugin system overview
+  - State machine: Redux
+  - Actions, Wrap Actions, Reducers, Selectors, Wrap Selectors, Components, Wrap Components
+  - Plugins vs. Presets (compare w. Babel: presets are collections of plugins)
+- Example custom plugins for common use cases (on spec update, replace a component, etc)
+- Example third-party plugin served via npm
+- Example custom layout
+- Disclaimer: plugins and components are not part of our public API. We'll make our best effort to minimize breaking changes, but you should pin a version if you're making heavy customizations.
+- 
+
+##### Core Development (8h)
+- Application architecture overview
+  - React + Redux + Reselect
+  - Custom plugin system (Editor is a plugin)
+- How to set up a local dev environment
+- Contribution guidelines
+- Linter and testing instructions
+- GitHub Issues workflow (priorities, labels, code review, etc)
+- Writing tests (JS unit, Enzyme unit, Nightwatch e2e)
+
+### Swagger-Editor
+
+##### Usage (6h)
+- Downloading the project via npm, git submodules, packagist, unkpg, direct clone
+- How to integrate with generic JS, React
+- How to use Docker image (basic + Docker Compose)
+- Editor-specific configuration options
+
+##### Customization (4h)
+- How to extend the validation and autocomplete systems
+
+##### Development (4h)
+- Validation and autocomplete system architecture
+- How to develop Editor and UI simultaneously with `npm link`
+
+### Swagger-Client (8h)
+- Basic usage in browser + Node
+- File uploads in browser + Node
+- Instance method documentation (`buildRequest`, `execute`, etc)

README.md

@@ -10,10 +10,10 @@
 
 As a brand new version, written from the ground up, there are some known issues and unimplemented features. Check out the [Known Issues](#known-issues) section for more details.
 
-This repo publishes to two different NPM packages:
+This repository publishes to two different NPM modules:
 
-* [swagger-ui](https://www.npmjs.com/package/swagger-ui) is intended for use as a node module.
-* [swagger-ui-dist](https://www.npmjs.com/package/swagger-ui-dist) comes pre-bundled with all dependencies and can be incorporated directly in a webapp.
+* [swagger-ui](https://www.npmjs.com/package/swagger-ui) is a traditional npm module intended for use in JavaScript web application projects that are capable of resolving dependencies (via Webpack, Browserify, etc).
+* [swagger-ui-dist](https://www.npmjs.com/package/swagger-ui-dist) is a dependency-free module that includes everything you need to serve Swagger-UI in a server-side project, or a web project that can't resolve npm module dependencies.
 
 For the older version of swagger-ui, refer to the [*2.x branch*](https://github.com/swagger-api/swagger-ui/tree/2.x).
 

src/core/components/array-model.jsx

@@ -41,7 +41,7 @@ export default class ArrayModel extends Component {
         {
           properties.size ? <span>
               { properties.entrySeq().map( ( [ key, v ] ) => <span key={`${key}-${v}`} style={propStyle}>
-                <br />{ `${key}:`}{ String(v) }</span>)
+                <br />{ key }: { String(v) }</span>)
               }<br /></span>
             : null
         }

src/core/components/primitive-model.jsx

@@ -23,6 +23,7 @@ export default class Primitive extends Component {
     let format = schema.get("format")
     let xml = schema.get("xml")
     let enumArray = schema.get("enum")
+    let title = schema.get("title") || name
     let description = schema.get("description")
     let properties = schema.filter( ( v, key) => ["enum", "type", "format", "description", "$$ref"].indexOf(key) === -1 )
     const Markdown = getComponent("Markdown")
@@ -30,7 +31,7 @@ export default class Primitive extends Component {
 
     return <span className="model">
       <span className="prop">
-        { name && <span className={`${depth === 1 && "model-title"} prop-name`}>{ name }</span> }
+        { name && <span className={`${depth === 1 && "model-title"} prop-name`}>{ title }</span> }
         <span className="prop-type">{ type }</span>
         { format && <span className="prop-format">(${format})</span>}
         {

src/style/_models.scss

@@ -237,7 +237,8 @@ span
 .prop-name
 {
     display: inline-block;
-    width: 100px;
+    margin-right: 1em;
+    width: 8em;
 }
 
 .prop-type

test/components/primitive-model.js

@@ -0,0 +1,49 @@
+/* eslint-env mocha */
+import React from "react"
+import expect from "expect"
+import { shallow } from "enzyme"
+import { fromJS } from "immutable"
+import PrimitiveModel from "components/primitive-model"
+
+describe("<PrimitiveModel/>", function() {
+    describe("Model name", function() {
+        const dummyComponent = () => null
+        const components = {
+            Markdown: dummyComponent,
+            EnumModel: dummyComponent
+        }
+        const props = {
+            getComponent: c => components[c],
+            name: "Name from props",
+            depth: 1,
+            schema: fromJS({
+                type: "string",
+                title: "Custom model title"
+            })
+        }
+
+        it("renders the schema's title", function() {
+            // When
+            const wrapper = shallow(<PrimitiveModel {...props}/>)
+            const modelTitleEl = wrapper.find("span.model-title")
+            expect(modelTitleEl.length).toEqual(1)
+
+            // Then
+            expect( modelTitleEl.text() ).toEqual( "Custom model title" )
+        })
+
+        it("falls back to the passed-in `name` prop for the title", function() {
+            // When
+            props.schema = fromJS({
+                type: "string"
+            })
+            const wrapper = shallow(<PrimitiveModel {...props}/>)
+            const modelTitleEl = wrapper.find("span.model-title")
+            expect(modelTitleEl.length).toEqual(1)
+
+            // Then
+            expect( modelTitleEl.text() ).toEqual( "Name from props" )
+        })
+
+    })
+} )

test/core/utils.js

@@ -583,7 +583,7 @@ describe("utils", function() {
     })
   })
 
-  describe.only("getAcceptControllingResponse", () => {
+  describe("getAcceptControllingResponse", () => {
     it("should return the first 2xx response with a media type", () => {
       const responses = fromJSOrdered({
         "200": {