Creating a custom layout

Layouts are a special type of component that Swagger UI uses as the root component for the entire application. You can define custom layouts in order to have high-level control over what ends up on the page.

By default, Swagger UI uses BaseLayout, which is built into the application. You can specify a different layout to be used by passing the layout’s name as the layout parameter to Swagger UI. Be sure to provide your custom layout as a component to Swagger UI.

For example, if you wanted to create a custom layout that only displayed operations, you could define an OperationsLayout:

1
import React from "react"
2

3
// Create the layout component
4
class OperationsLayout extends React.Component {
5
  render() {
6
    const {
7
      getComponent
8
    } = this.props
9

10
    const Operations = getComponent("operations", true)
11

12
    return (
13
      <div className="swagger-ui">
14
        <Operations />
15
      </div>
16
    )
17
  }
18
}
19

20
// Create the plugin that provides our layout component
21
const OperationsLayoutPlugin = () => {
22
  return {
23
    components: {
24
      OperationsLayout: OperationsLayout
25
    }
26
  }
27
}
28

29
// Provide the plugin to Swagger-UI, and select OperationsLayout
30
// as the layout for Swagger-UI
31
SwaggerUI({
32
  url: "https://petstore.swagger.io/v2/swagger.json",
33
  plugins: [ OperationsLayoutPlugin ],
34
  layout: "OperationsLayout"
35
})

Augmenting the default layout

If you’d like to build around the BaseLayout instead of replacing it, you can pull the BaseLayout into your custom layout and use it:

1
import React from "react"
2

3
// Create the layout component
4
class AugmentingLayout extends React.Component {
5
  render() {
6
    const {
7
      getComponent
8
    } = this.props
9

10
    const BaseLayout = getComponent("BaseLayout", true)
11

12
    return (
13
      <div>
14
        <div className="myCustomHeader">
15
          <h1>I have a custom header above Swagger-UI!</h1>
16
        </div>
17
        <BaseLayout />
18
      </div>
19
    )
20
  }
21
}
22

23
// Create the plugin that provides our layout component
24
const AugmentingLayoutPlugin = () => {
25
  return {
26
    components: {
27
      AugmentingLayout: AugmentingLayout
28
    }
29
  }
30
}
31

32
// Provide the plugin to Swagger-UI, and select AugmentingLayout
33
// as the layout for Swagger-UI
34
SwaggerUI({
35
  url: "https://petstore.swagger.io/v2/swagger.json",
36
  plugins: [ AugmentingLayoutPlugin ],
37
  layout: "AugmentingLayout"
38
})