openapi_tools 0.5.1

Tools for working with OpenAPI specs
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121

# OpenAPI Tools

A crate for working with OpenAI specifications.

Currently there's only one feature implented:

## Merge

The merge command can be used to merge multiple OpenAPI spec files into one.

This might be useful, for instance, if you have multiple services behind the same API and you want to keep the OpenAPI spec next to the code for each service.

### Usage

```
Usage: openapi_tools merge [OPTIONS]

Options:
  -f, --file <FILE>
          The filename of the main template file
  -j, --json <JSON>
          The template as json
  -y, --yaml <YAML>
          The template  as yaml
  -e, --encoding <ENCODING>
          The template encoding (defaults to the file extension) [possible values: json, yaml, yml]
  -v, --var <TEMPLATE_VARS>
          Template variables
  -o, --output-file <OUTPUT>
          Output file path (if not specified, the result will print to stdout)
  -E, --output-encoding <OUTPUT_FORMAT>
          Output encoding (default is json) [possible values: json, yaml, yml]
  -w, --working-dir <WORKING_DIRECTORY>
          Paths in the template will be resolved relative to this directory (defaults to cwd)
  -h, --help
          Print help                          Print help
```

This command requires a template, which can be either specified using the `file` argument, or passed directoy using the `json` or `yaml` argument.

Here the template is like a normal OpenAPI spec, except that it has an extra `sources` dictionary, which can be used to specify other OpenAPI specs to merge into the final result.

So for instance, if we had this structure:

```
monorepo/
  service1/
    api-spec.yaml
  service2/
    api-spec.yaml
  api-spec.template.yaml
```

And our openapi specifications look like this:

#### `service1/api-spec.yaml`:

```
openapi: "3.0.0"
info:
  title: "Service 1"
  version: "1.0.0"
paths:
  /foo:
    get:
      responses:
        "200":
          description: OK
```

#### `service1/api-spec.yaml`:
```
openapi: "3.0.0"
info:
  title: "Service 2"
  version: "1.0.0"
paths:
  /bar:
    get:
      responses:
        "200":
          description: OK
```

#### `api-spec.template.yaml`:

```
openapi: "3.0.0"
info:
  title: "Combined Service"
  version: "1.0.0"
sources:
  ./service1/api-spec.yaml:
  ./service2/api-spec.yaml:
```

Running this command:

```
$ openapi_tools merge --file api-spec.template.yaml -F yaml
```

Will produce this result:

```
openapi: 3.0.3
info:
  title: 'Combined Service'
  version: '1.0.0'
paths:
  /foo:
    get:
      responses:
        '200':
          description: OK
  /bar:
    get:
      responses:
        '200':
          description: OK
```