30 April: Auto-updating API reference docs, design improvements, editor updates and more

There’s a new home for your OpenAPI specification that makes generating and updating API reference docs effortless, plus a bunch of other improvements.

✨ New and noteworthy

Create auto-updating API docs in seconds

We’ve added a new way to generate beautiful API documentation from an OpenAPI specification in seconds. The new OpenAPI section in the sidebar lets you add your spec from a URL, upload it as a file, or using the GitBook CLI.

Once added to your organization, it’s super easy to use the spec to generate OpenAPI blocks — or a complete API reference — in any space.

You can update your OpenAPI specification at any time using the GitBook UI or the CLI, regardless of how it was initially added. But if you add it using a URL, GitBook will automatically check for updates every six hours. Any changes will be pushed to your API docs right away.

You can add multiple specifications to your org if needed, so you can document all the APIs you want effortlessly. And best of all, your API docs can pull all kinds of extra content from your spec file — including page icons, page descriptions, object description, and all the endpoints.

Everything is generated from the specification, and formatted beautifully by GitBook (more on that below), with on-page testing for your users.

This is how we created our own API reference docs, so head over there to check it out. Everything in those API Reference pages is pulled from the spec.

Head to our docs to read more about this — we’ve also written a handy guide if you want to get this set up for your own organization.

Improved OpenAPI and code block designs

While working on this new API process, we’ve also been working on some visual improvements to API blocks (and code blocks) to make your docs looks better than ever.

A cleaner layout for OpenAPI blocks

We’ve tweaked the OpenAPI block’s layout to remove some unnecessary separators, and make property names bolder for clearer reading. We’ve also made property titles more consistent.

Improved OpenAPI object accordions

We’ve also reworked object accordions to make them easier to work with. The entire property is now clickable, so clicking anywhere within it will reveal its child schemas. And when you hover over a property, a button will appear to show it can be expanded.

On mobile, and other devices that don’t support hover actions, this button will always appear to make it clear that the property is expandable.

New schema alternatives separators

For schemes with alternatives, we now display a new separator. The new options include anyOf, allOf, and oneOf. The separators use string translations for different languages.

New color palette for code blocks (including high-contrast version when requested by the browser)

API blocks and code blocks have also had a color update.

In published docs, API and code blocks will now use your site’s primary, tint and semantic colors to style the code blocks. So if you’ve set all your colors to carefully follow your brand guidelines, code blocks will now reflect those colors (and the effort you’ve put into adding them).

They will also show a high-contrast version automatically when requested by a user’s browser.

These changes apply to both code blocks and OpenAPI panels that contain code, so everything will be consistent across your site.

Even more editor improvements

Following on from our last few updates, the team has continued their work across the editor to improve the performance and the user experience in the GitBook app. Here’s a quick roundup of what’s new!

All-new palette styles

We’ve refreshed the palettes in the GitBook app. They are now more in line with the other UI elements and generally look a little nicer.

The change has been rolled out to all the menus in the app, and we’re working on improving the UX of some of these palettes too.

We’ve started with the link palette. It previously showed all the linkable content in your organization in one long list, which could make results tricky to find. Now, different content is separated by titles, so it’s easier to see other section on the current page, other pages in the same space, other spaces and users.

We’ve also made the inline palette searchable. So if you want to add an inline image, emoji, link or Math & TeX, you can now search the menu with your keyboard rather than needing to use your cursor or the up/down arrow keys.

Icons for relative links

Relative links — aka links to other pages within your docs — will now display that content’s icon or emoji next to the space/page title in the editor. Before they’d show a space, page or anchor link icon. Now they’ll use the icon you’ve selected for the link target. /

A bunch of smaller improvements

We’ve improved the way that the GitBook editor handles images in image blocks. Now we’ll automatically resized the version that displays within the editor, making the loading times faster and editing smoother. Plus, if you have more than one image in a single image block, you can now drag and drop them horizontally to reorder them.
We’ve made a few small tweaks to the UI for table and card blocks. Specifically, GitBook now hides the Options menu for blocks within a table or card, so they only appear when you hover near the block. We’ve also changed the padding for the buttons, as they were previously getting cut off within cards.
We’ve improved tab blocks — specifically linking to specific tabs within a tab block. Before, clicking an anchor link to a tab on the same page would open it in a new browser tab/window. You can also make tab blocks full width, giving you more room if you want to create tabs with lots of tab items or long headings.
You can now use subscript and superscript formatting options — just highlight your text and choose the new options from the inline palette! So now you can write things like H2O and 16th, if you want.

Improved

We’ve made site redirects better by making it a distinct section within your site’s Settings menu, and showing more redirects on the screen at once.
Hitting the right/left arrow keys in a table will now switch between cells when you reach the start or end of an input.
Using the insert menu to add a block to an empty block in the editor now replaces the empty block with the new block, instead of adding it above the empty block.

Fixed

Fixed an issue where text pasted into code block as Markdown would show the syntax data (e.g. ```typescript) as lines of code. Now it should paste as expected, without that data.
Fixed an issue that meant it was possible to embed reusable content inside more reusable content if it was imported from GitHub or GitLab using Git Sync.
Fixed an issue that prevented negative numbers from being included in number cells within tables.
Fixed an infinitely-loading pop-up message when cancelling a file import.
Fixed an issue that was making it hard to select text within a table cell.
Fixed an issue that meant reusable content could not be selected, and fixed a separate issue that meant reusable content instances could not be detached, and another that meant full-width blocks within reusable content did not display correctly.

Fixed an issue that could cause an image to be lost when converting it from an inline image to an image block.

We’re constantly working to improve the way you and your team work in GitBook, and value your input on features, bugs, and more. Make sure you head to our official GitBook community to join the discussion.

Last updated 3 hours ago

Was this helpful?