There’s a new home for your OpenAPI specification that makes generating and updating API reference docs effortless, plus a bunch of other improvements.
Last updated
Was this helpful?
Was this helpful?
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.
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.
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.
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.
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.
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!
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.
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. /
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.
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.
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.
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.