Documentation Missing

Q	A
Bug or feature request?	Feature
Which Swagger/OpenAPI version?	3.x
Which Swagger-Editor version?	3.1.4
How did you install Swagger-Editor?	npm i swagger-editor-dist
Which broswer & version?	Chrome
Which operating system?	MacOS

There are no docs for the editor API, which makes using it very difficult. Even a basic example of how to mount the editor with an existing spec would go a long way. In lieu of those, I have a couple questions:

1. How do you start the editor with a spec using a URL? (README says this is missing)
2. How do you start the editor with a spec in memory?
3. How do you listen/subscribe/hook changes to the editor’s value (the current spec)?
4. How do you set the editors value?

[kyeotic]

Well I managed to figure out some of those out on my own. This is the wrapper I came up with.

class SwaggerEditor extends Component {
  componentDidMount () {
    this.editor = window.SwaggerEditorBundle({
      dom_id: '#swagger-editor',
      spec: {},
      layout: 'StandaloneLayout',
      presets: [
        window.SwaggerEditorStandalonePreset
      ]
    })
    this.setEditorValue(this.props.spec || '')
    this.unsubscribe = this.editor.getStore().subscribe(this.handleChange)
  }
  componentWillUnmount () {
    this.unsubscribe()
  }
  componentDidUpdate (prevProps, prevState) {
    if (prevProps.spec === this.props.spec) {
      this.syncEditorValue(this.props.spec || '')
    }
  }
  setEditorValue = (value) => {
    this.editor.specActions.updateSpec(value)
  }

  handleChange = () => {
    let newValue = this.editor.getState().getIn(['spec', 'spec'])
    if (newValue !== this.props.spec && !(this.props.spec === null && newValue === '')) {
      this.props.onChange(newValue)
    }
  }

  render () {
    return <div id='swagger-editor' className='swagger-editor' />
  }
}

[shockey]

@tyrsius, my apologies for dropping the ball here - this was mistakenly not tagged as a Support ticket for your questions.

How do you start the editor with a spec using a URL? (README says this is missing)

There’s currently no officially supported way to do this (there’s some work that needs to be done on it, for example it should convert JSON to YAML when it imports), but the Editor will pick up on a url configuration option. You can set it in the configuration object you pass to Swagger-Editor, or in the query string of the URL you’re using to access the Editor.

How do you start the editor with a spec in memory?

Again, this is not officially supported, but you can pass a spec as a JavaScript object in through the configuration object only, as the spec option.

If you want to add YAML… that’s trickier. You’ll need to reach into the Editor’s internals to do that, here’s an example:

const editor = SwaggerEditor({
  dom_id: '#swagger-editor'
})

const myYamlSpec = "swagger: 2.0\ninfo:\n  title: Here is my spec"

editor.specActions.updateSpec(myYamlSpec)

This method is not part of our public API, and may change when the project’s minor version changes. That said, it hasn’t changed since 3.0.0.

How do you listen/subscribe/hook changes to the editor’s value (the current spec)?

You can write a plugin that achieves this:

const SpecUpdateListenerPlugin = function() {
  return {
    statePlugins: {
      spec: {
        wrapActions: {
          updateSpec: (oriAction) => (...args) => {
            const [str] = args
            console.log(str)
            return oriAction(...args)
          }
        }
      }
    }
  }
}

SwaggerEditor({
    dom_id: '#swagger-editor',
  plugins: [
    SpecUpdateListenerPlugin
  ]
})

How do you set the editors value?

See my answer above that uses updateSpec.

---

Hopefully this helps. The use cases your questions allude to are valid, and I’d love to see first-class interfaces for them (I imagine a onEditorValueChange callback config option, and a better spec option, for starters), but our resources are limited - if you have the time to submit a PR for any of this, it’d be appreciated!