Skip to content

Commit

Permalink
docs: Use Museum API instead of Petstore examples (#1386)
Browse files Browse the repository at this point in the history 
* docs: add museum examples to installation and bundle/join commands

* docs: removed petstore examples and updated formatting for readability

* docs: Update petstore to museum examples in decorators section

* chore: Prettier wants to fix a file

* chore: Fix Vale-detected future tense mistakes

* Update docs/decorators/media-type-examples-override.md

* Update docs/commands/lint.md

* Update docs/commands/lint.md

---------

Co-authored-by: Heather Cloward <[email protected]>
  • Loading branch information
@lornajane @HCloward
lornajane and HCloward authored Feb 12, 2024
1 parent 4a913d6 commit fd79f7d
Show file tree
Hide file tree
Showing 5 changed files with 273 additions and 328 deletions.
98 changes: 3 additions & 95 deletions docs/commands/bundle.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -62,20 +62,20 @@ redocly bundle openapi/openapi.yaml --output dist/openapi.json
This command creates one bundled file for each of the specified apis in the `dist/` folder. Bundled files are in JSON format.

```bash Command
redocly bundle --output dist --ext json openapi/openapi.yaml openapi/petstore.yaml
redocly bundle --output dist --ext json openapi/openapi.yaml openapi/museum.yaml
```

```bash Output
dist/openapi.json
dist/petstore.json
dist/museum.json
```

### Create a fully dereferenced bundle

A fully dereferenced bundle does not use `$ref` at all, all the references are resolved and placed into the API description file. This can be useful if you need to prepare an OpenAPI file to be used by another tool that does not understand the `$ref` syntax.

```bash
redocly bundle --dereferenced --output dist --ext json openapi/openapi.yaml openapi/petstore.yaml
redocly bundle --dereferenced --output dist --ext json openapi/openapi.yaml openapi/museum.yaml
```

{% admonition type="warning" name="Note" %}
Expand All @@ -90,98 +90,6 @@ By default, the CLI tool looks for the Redocly configuration file in the current
redocly bundle --config=./another/directory/config.yaml
```

### Format

#### Codeframe (default)

```bash
redocly bundle pet.yaml store.yaml -o ./bundled --format=codeframe
## equivalent to: redocly bundle pet.yaml store.yaml -o ./bundled
```

Note: Errors display in the following format: `file:line:column`. For example, `petstore-with-errors.yaml:16:3`.

Depending on the terminal emulator you use, it may be possible to directly click this indicator to edit the file in place.

#### Stylish

```bash
redocly bundle pet.yaml store.yaml -o ./bundled --format=stylish
```

In this format, `bundle` shows the filename, line number, and column where the problem occurred.

The compressed output omits other contexts and suggestions.

#### JSON

{% tabs %}
{% tab label="Command" %}

```bash
redocly bundle pet.yaml store.yaml -o ./bundled --format=json
```

{% /tab %}
{% tab label="Output" %}

```bash
bundling pet.yaml...
{
"totals": {
"errors": 0,
"warnings": 0,
"ignored": 0
},
"version": "1.0.0-beta.54",
"problems": []
}📦 Created a bundle for pet.yaml at bundled/pet.yaml 28ms.
bundling store.yaml...
{
"totals": {
"errors": 0,
"warnings": 0,
"ignored": 0
},
"version": "1.0.0-beta.54",
"problems": []
}📦 Created a bundle for store.yaml at bundled/store.yaml 15ms.
```

{% /tab %}
{% /tabs %}

In this format, `bundle` shows the result of bundling (including the number of errors and warnings and their descriptions) in JSON-like output.

#### Checkstyle

{% tabs %}
{% tab label="Command" %}

```bash
redocly bundle pet.yaml -o ./bundled --lint --format=checkstyle
```

{% /tab %}
{% tab label="Output" %}

```bash
bundling pet.yaml...
<?xml version="1.0" encoding="UTF-8"?>
<checkstyle version="4.3">
<file name="pet.yaml">
</file>
</checkstyle>
📦 Created a bundle for pet.yaml at bundled/pet.yaml 35ms.
```

{% /tab %}
{% /tabs %}
In this format, `bundle` uses the [Checkstyle](https://checkstyle.org/) XML report format.
Due to the limitations of this format, the output _only_ includes the filename, line, column, severity,
and rule ID (in the `source` attribute).
All other information is omitted.

### Skip preprocessor, rule, or decorator

You may want to skip specific preprocessors, rules, or decorators upon running the command.
Expand Down
101 changes: 57 additions & 44 deletions docs/commands/join.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -105,7 +105,7 @@ x-tagGroups:
description: 'Text from info: description of the first input file'
- name: second-api
tags:
- pets
- partner
description: 'Text from info: description of the second input file'
```
Expand All @@ -123,17 +123,17 @@ Path names and component names must be unique in all input files, but their cont
If the `join` command detects any conflicting content while trying to combine the input files, it displays informative messages about the conflicts and exits without creating an output file. To prevent this, use optional parameters to add prefixes to tags and components.

```bash
Conflict on tags => all : pets in files: petstore.yaml,test.yaml
Conflict on tags => all : tickets in files: museum.yaml,exhibition.yaml
1 conflict(s) on tags.
Suggestion: please use prefix-tags-with-filename, prefix-tags-with-info-prop or without-x-tag-groups to prevent naming conflicts.
Conflict on paths => /pets : get in files: petstore.yaml,test.yaml
Conflict on paths => /pets : post in files: petstore.yaml,test.yaml
Conflict on paths => operationIds : listPets in files: petstore.yaml,test.yaml
Conflict on paths => operationIds : createPets in files: petstore.yaml,test.yaml
Conflict on paths => operationIds : showPetById in files: petstore.yaml,test.yaml
Conflict on paths => /pets/{petId} : get in files: petstore.yaml,test.yaml
Conflict on paths => /tickets : get in files: museum.yaml,exhibition.yaml
Conflict on paths => /tickets : post in files: museum.yaml,exhibition.yaml
Conflict on paths => operationIds : listEvents in files: museum.yaml,exhibition.yaml
Conflict on paths => operationIds : createEvent in files: museum.yaml,exhibition.yaml
Conflict on paths => operationIds : getEvent in files: museum.yaml,exhibition.yaml
Conflict on paths => /tickets/{Id} : get in files: museum.yaml,exhibition.yaml
Please fix conflicts before running join.
```
Expand Down Expand Up @@ -167,9 +167,9 @@ redocly join first-api.yaml second-api.json --prefix-tags-with-info-prop title
description: endpoints tag description
x-displayName: endpoints
- name: Second document title_pets
description: pets tag description
x-displayName: pets
- name: Second document title_events
description: events tag description
x-displayName: events
```

{% /tab %}
Expand Down Expand Up @@ -198,9 +198,9 @@ redocly join first-api.yaml second-api.json --prefix-tags-with-filename true
description: endpoints tag description
x-displayName: endpoints
- name: second-api_pets
description: pets tag description
x-displayName: pets
- name: second-api_events
description: events tag description
x-displayName: events
```

{% /tab %}
Expand Down Expand Up @@ -230,11 +230,8 @@ If any of the input files have conflicting component names, this option can be u

#### Usage

{% tabs %}
{% tab label="Command" %}

```bash
redocly join first-api.yaml second-api.json --prefix-components-with-info-prop version
redocly join museum_v1.yaml museum_v2.json --prefix-components-with-info-prop version
```

{% /tab %}
Expand All @@ -243,35 +240,51 @@ redocly join first-api.yaml second-api.json --prefix-components-with-info-prop v
```yaml
components:
schemas:
1.0.1_Pet:
allOf:
- $ref: '#/components/schemas/NewPet'
- type: object
required:
- id
properties:
id:
type: integer
format: int64
1.0.1_NewPet:
1.0.0_BuyMuseumTicketsRequest:
description: Request payload used for purchasing museum tickets.
type: object
properties:
ticketType:
$ref: '#/components/schemas/1.0.0_TicketType'
eventId:
description: >-
Unique identifier for a special event. Required if purchasing
tickets for the museum's special events.
$ref: '#/components/schemas/1.0.0_1.0.0_EventId'
ticketDate:
description: Date that the ticket is valid for.
$ref: '#/components/schemas/1.0.0_1.0.0_Date'
email:
$ref: '#/components/schemas/1.0.0_Email'
phone:
$ref: '#/components/schemas/1.0.0_Phone'
required:
- name
- ticketType
- ticketDate
- email
1.2.0_BuyMuseumTicketsRequest:
description: Request payload used for purchasing museum tickets.
type: object
properties:
name:
type: string
tag:
type: string
1.2.0_Pet:
allOf:
- $ref: '#/components/schemas/NewPet'
- type: object
required:
- id
properties:
id:
type: integer
format: int64
ticketType:
$ref: '#/components/schemas/1.2.0_TicketType'
eventId:
description: >-
Unique identifier for a special event. Required if purchasing
tickets for the museum's special events.
$ref: '#/components/schemas/1.2.0_1.2.0_EventId'
ticketDate:
description: Date that the ticket is valid for.
$ref: '#/components/schemas/1.2.0_1.2.0_Date'
email:
$ref: '#/components/schemas/1.2.0_Email'
phone:
$ref: '#/components/schemas/1.2.0_Phone'
required:
- ticketType
- ticketDate
- email
```

{% /tab %}
Expand Down
Loading

1 comment on commit fd79f7d

@github-actions
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Coverage report

St.❔
 Category Percentage Covered / Total
🟡 Statements 76.1% 4302/5653
🟡 Branches 65.72% 2232/3396
🟡 Functions 68.81% 695/1010
🟡 Lines 76.31% 4045/5301

Test suite run success

699 tests passing in 100 suites.

Report generated by 🧪jest coverage report action from fd79f7d

Please sign in to comment.