Swagger-editor: Documentation Missing

[kyeotic]

| 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?

[shockey]

This is an oversight on our part 😬

For starters, you can use any parameters mentioned in Swagger-UI's documentation: https://github.com/swagger-api/swagger-ui#parameters

I'll keep this open so we can get around to documenting this in the Editor README, and some better documentation of Editor-specific things.

[kyeotic]

@shockey If I could just get setting/reading the editor value I could get around everything else, but it doesn't look like there is a way to do that from the outside

[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!

[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]

Glad to hear it!

I'm going to leave this issue open, as I'd like to see these cases addressed in our documentation as common examples of how to use the plugin system.

[Codermar]

@tyrsius Can you provide a more complete example of how you implemented your customization of the editor? Thanks!

[mshetty794]

@kyeotic how can we use SwaggerEditorBundle to download YAML file

[kyeotic]

@Codermar What? I already provided the entire customized editor. Are you asking for the entire application?

@mshetty794 If you take the example I provided above you can collect the value from the editor. Downloading a string as a file is a generic process, not one specific to the this case. Just look up "javascript how to save a string as file"