Skip to content

Commit 7e2f27a

Browse files
gregbergegitbook-bot
gregberge
authored and
gitbook-bot
committed
GITBOOK-595: No subject
1 parent c824f07 commit 7e2f27a

11 files changed

+127
-93
lines changed

‎SUMMARY.md

+6-3
Original file line numberDiff line numberDiff line change
@@ -57,15 +57,18 @@
5757

5858
* [OpenAPI](api-references/openapi/README.md)
5959
* [Add an OpenAPI specification](api-references/openapi/add-an-openapi-specification.md)
60-
* [Organize your endpoints](api-references/openapi/organize-your-endpoints.md)
61-
* [Extensions reference](api-references/openapi/extensions-reference.md)
60+
* [Insert API reference in your docs](api-references/openapi/insert-api-reference-in-your-docs.md)
6261
* [Guides](api-references/guides/README.md)
6362
* [Structuring your API reference](api-references/guides/structuring-your-api-reference.md)
6463
* [Adding custom code samples](api-references/guides/adding-custom-code-samples.md)
65-
* [Managing API endpoints](api-references/guides/managing-api-endpoints.md)
64+
* [Managing API operations](api-references/guides/managing-api-operations.md)
6665
* [Describing enums](api-references/guides/describing-enums.md)
6766
* [Integrating with CI/CD](api-references/guides/support-for-ci-cd-with-api-blocks.md)
6867

68+
***
69+
70+
* [Extensions reference](extensions-reference.md)
71+
6972
## Publishing Documentation
7073

7174
* [Publish a docs site](publishing-documentation/publish-a-docs-site/README.md)

‎api-references/guides/adding-custom-code-samples.md

+3-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
---
2-
description: Configure custom code samples to display alongside your API endpoints.
2+
description: >-
3+
Learn how to configure custom code samples to display alongside your API
4+
endpoints.
35
---
46

57
# Adding custom code samples

‎api-references/guides/describing-enums.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
description: Add descriptions to operations that include enums.
2+
description: Learn how to add descriptions to enums.
33
---
44

55
# Describing enums

‎api-references/guides/managing-api-endpoints.md renamed to ‎api-references/guides/managing-api-operations.md

+8-2
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,14 @@
1-
# Managing API endpoints
1+
---
2+
description: >-
3+
Learn how to mark an OpenAPI API operation as experimental, deprecated or hide
4+
it from your documentation.
5+
---
6+
7+
# Managing API operations
28

39
{% include "../../.gitbook/includes/openapi-availability-hint.md" %}
410

5-
It’s common to have endpoints that are not fully stable yet or that need to be phased out. GitBook supports several OpenAPI extensions to help you manage these scenarios.
11+
It’s common to have operations that are not fully stable yet or that need to be phased out. GitBook supports several OpenAPI extensions to help you manage these scenarios.
612

713
### Marking operation as experimental, alpha, or beta
814

‎api-references/guides/structuring-your-api-reference.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
description: >-
3-
Structure your API reference across multiple pages with icons and
3+
Learn how to structure your API reference across multiple pages with icons and
44
descriptions.
55
---
66

‎api-references/guides/support-for-ci-cd-with-api-blocks.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
description: How to use GitBook’s OpenAPI method blocks to support a CI/CD workflow
2+
description: Learn how to automate the update of your OpenAPI specification in GitBook.
33
---
44

55
# Integrating with CI/CD

‎api-references/openapi/README.md

+1-13
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
description: >-
33
Add an OpenAPI spec to a page and let your users test endpoints right on the
4-
page with interactive blocks
4+
page with interactive blocks.
55
icon: brackets-curly
66
---
77

@@ -24,15 +24,3 @@ GitBook supports [Swagger 2.0](https://github.com/OAI/OpenAPI-Specification/blob
2424
GitBook's OpenAPI block also supports a "test it" functionality, which allows your users to test your API methods with data and parameters filled in from the editor.
2525

2626
Powered by [Scalar](https://scalar.com/), you won't need to leave the docs in order to see your API methods in action. See and example of this above.
27-
28-
### API method block (deprecated)
29-
30-
{% hint style="warning" %}
31-
**Editable API method blocks are now deprecated**
32-
33-
In light of our updated OpenAPI method block, **we’ve decided to deprecate the API method block.** [Read our recent announcement](https://changelog.gitbook.com/announcements/depreciating-api-method-block) to find out more about the reasons behind this change.
34-
35-
On **Monday 4 March 2024**, we automatically transitioned all pre-existing API method blocks to regular blocks in the format you can see below. [Read our announcement](https://changelog.gitbook.com/announcements/depreciating-api-method-block) to find out more.
36-
{% endhint %}
37-
38-
You can still create editable API references from the **Quickstart** section of the **Insert menu**. Hit / on your keyboard and select **API Reference**.

‎api-references/openapi/add-an-openapi-specification.md

+30-14
Original file line numberDiff line numberDiff line change
@@ -1,36 +1,52 @@
1+
---
2+
description: >-
3+
Learn how to add and update an OpenAPI specification in GitBook application or
4+
from CLI.
5+
---
6+
17
# Add an OpenAPI specification
28

39
{% include "../../.gitbook/includes/openapi-availability-hint.md" %}
410

5-
If you have an OpenAPI specification, you can add it directly to your organization. You can link your specification via the URL of a hosted OpenAPI document, or by uploading the OpenAPI file directly.
11+
If you have an OpenAPI spec, you can add it to your organization by uploading the file directly, linking to a hosted URL, or using the [GitBook CLI](https://app.gitbook.com/s/2SyQSbIa1iYS7z6Dx5di/cli).
612

713
<figure><img src="../../.gitbook/assets/02_04_25_add_api_spec.svg" alt=""><figcaption></figcaption></figure>
814

9-
### Add a specification
10-
11-
To add a specification, head to the OpenAPI panel in the sidebar. Here you’ll be able to upload a file, link via URL to your existing OpenAPI specification, or use our [CLI](https://docs.gitbook.com/developers/cli/quickstart) to publish your OpenAPI spec to GitBook.
15+
### How to add a specification
1216

13-
You’ll need to give your specification a name, which will be its identifier if you add more than 1 specification to your organization.
17+
1. Open the **OpenAPI** section in the sidebar
18+
2. Click on **Add specification**
19+
3. Give your specification a name. This helps identify it, especially if you manage multiple specs
20+
4. Choose one of the following:
21+
* Upload a file (e.g. _openapi.yaml_)
22+
* Enter a URL to a hosted spec
23+
* Use the CLI to publish the spec
1424

1525
<figure><img src="../../.gitbook/assets/03_04_25_api_spec_modal (1).svg" alt=""><figcaption><p>Add an OpenAPI specification modal.</p></figcaption></figure>
1626

1727
### Update your specification
1828

19-
From time to time you might need to update or modify your API specification.&#x20;
29+
You can update your OpenAPI specification at any time using the GitBook UI or the CLI, regardless of how it was initially added.
2030

21-
#### Updating your specification via URL
31+
#### In GitBook Application
2232

23-
If you added your specification via URL, GitBook will automatically check for updates every 6 hours. If you need to update your specification faster than that, click the “Check for updates” button in the upper right corner of the OpenAPI section.
33+
In the OpenAPI panel:
2434

25-
#### Updating your specification via file
35+
* If your spec is linked to a URL:
36+
* GitBook checks for updates automatically **every 6 hours**.
37+
* To fetch updates immediately, click **Check for updates**.
38+
* If your spec was uploaded as a file:
39+
* Click **Update** to upload a new version.
40+
* You can switch from a File to a URL source by clicking on **Edit** in the breadcrumb actions menu.
2641

27-
To update your OpenAPI spec if you’ve added it as a file, click the “Update” button in the upper right corner of the OpenAPI section to update or replace the file.
42+
#### Using the CLI
2843

29-
#### Updating your specification via CLI
30-
31-
If you’ve used the [CLI](https://docs.gitbook.com/developers/cli/quickstart) to add an OpenAPI specification, you can update it by running the same command:
44+
Use the same command to update your specification:
3245

3346
```bash
34-
gitbook openapi publish --spec api-spec-name --organization organization_id <path-to-openapi-file>
47+
gitbook openapi publish --spec api-spec-name --organization organization_id <path-or-url>
3548
```
3649

50+
You can also use the CLI to **Check for updates** by running the publish command on the same URL.
51+
52+
Read our [support-for-ci-cd-with-api-blocks.md](../guides/support-for-ci-cd-with-api-blocks.md "mention") guide to learn how to automate the update of your specification.

‎api-references/openapi/insert-api-reference-in-your-docs.md

+69
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
---
2+
description: >-
3+
Insert complete API reference from your OpenAPI spec or pick individual
4+
operation or schemas.
5+
---
6+
7+
# Insert API reference in your docs
8+
9+
{% include "../../.gitbook/includes/openapi-availability-hint.md" %}
10+
11+
GitBook allows you to automatically generate pages related to the endpoints you have in your OpenAPI spec. These pages will contain OpenAPI operation blocks, allowing you and your visitors to test your endpoints and explore them further based on the information found in the spec.
12+
13+
{% hint style="success" %}
14+
Endpoints added from your spec will continue to be updated anytime your spec is updated. See the [Update your specification](add-an-openapi-specification.md#update-your-specification) section for more info.
15+
{% endhint %}
16+
17+
### Automatically create OpenAPI pages from your spec
18+
19+
After you’ve [added your OpenAPI spec](add-an-openapi-specification.md), you can generate endpoint pages by inserting an **OpenAPI Reference** in the table of contents of a Space.
20+
21+
<figure><img src="../../.gitbook/assets/03_04_25_create_api_pages.svg" alt=""><figcaption><p>Insert API References in the table of contents of a Space.</p></figcaption></figure>
22+
23+
{% stepper %}
24+
{% step %}
25+
### Generate pages from OpenAPI
26+
27+
In the space you’d like to generate endpoint pages, click the **Add new...** button from the bottom of your space’s [table of contents](../../resources/gitbook-ui.md#table-of-contents).
28+
29+
From here, click **OpenAPI Reference**.
30+
{% endstep %}
31+
32+
{% step %}
33+
### Choose your OpenAPI spec
34+
35+
Choose your previously uploaded OpenAPI spec, and click **Insert** to automatically add your endpoints to your space. You can optionally choose to add a models page referencing all your OpenAPI schemas.
36+
{% endstep %}
37+
38+
{% step %}
39+
### Manage your API operations
40+
41+
GitBook will automatically generate pages based on your OpenAPI spec and the tags set inside it’s definition.&#x20;
42+
43+
Head to [structuring-your-api-reference.md](../guides/structuring-your-api-reference.md "mention") to learn more about organizing your operations through your OpenAPI spec.
44+
{% endstep %}
45+
{% endstepper %}
46+
47+
### Add an individual OpenAPI block
48+
49+
Alternatively, you can add OpenAPI operations or schemas from your spec individually to pages throughout your docs.&#x20;
50+
51+
{% stepper %}
52+
{% step %}
53+
### Add a new OpenAPI block
54+
55+
Open the block selector by pressing **/**, and search for OpenAPI.
56+
{% endstep %}
57+
58+
{% step %}
59+
### Choose your OpenAPI spec
60+
61+
Choose your previously uploaded OpenAPI spec, and click **Continue** to choose your the endpoints you’d like to use.
62+
{% endstep %}
63+
64+
{% step %}
65+
### Choose the operations or schemas you’d like to insert
66+
67+
Pick the operations and the schemas you want to insert in your docs and click **Insert**.
68+
{% endstep %}
69+
{% endstepper %}

‎api-references/openapi/organize-your-endpoints.md

-55
This file was deleted.

‎api-references/openapi/extensions-reference.md renamed to ‎extensions-reference.md

+7-2
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,17 @@
1+
---
2+
description: The complete reference of OpenAPI extensions supported by GitBook.
3+
icon: code
4+
---
5+
16
# Extensions reference
27

3-
{% include "../../.gitbook/includes/openapi-availability-hint.md" %}
8+
{% include ".gitbook/includes/openapi-availability-hint.md" %}
49

510
You can enhance your OpenAPI specification using extensions—custom fields that start with the `x-` prefix. These extensions let you add extra information and tailor your API documentation to suit different needs.
611

712
GitBook allows you to adjust how your API looks and works on your published site through a range of different extensions you can add to your OpenAPI spec.&#x20;
813

9-
Head to our [guides section](../guides/) to learn more about using OpenAPI extensions to configure your documentation.
14+
Head to our [guides section](api-references/guides/) to learn more about using OpenAPI extensions to configure your documentation.
1015

1116
<details>
1217

0 commit comments

Comments
 (0)