openapi_type 0.6.0

OpenAPI type information for Rust structs and enums
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
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172

# openapi_type [![Rust Version: 1.95.0](https://img.shields.io/badge/rustc-1.95.0-orange.svg)](https://github.com/rust-lang/rust/releases/tag/1.95.0) [![License Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0) [![Git repository on Codeberg](https://img.shields.io/badge/Code-On%20Codeberg-blue?logo=Codeberg)](https://codeberg.org/msrd0/openapi_type)

This crate gives static type information for primitives and commonly used types from
the standard library and other commonly used libraries (see [features](#features))
when the according feature is enabled. Please refer to the [`Cargo.toml`][__link0] for a list
of all available feature flags and optional dependencies. Also, it provides a derive
macro for structs and enums to gain access to their static type information at
runtime.

The core of this crate is the [`OpenapiType`][__link1] trait. It has three static function,
where [`schema`][__link2], which returns an [`OpenapiSchema`][__link3], is the one
you are probably looking for. It assembles the static type information in a way that
is convenient to use for a generated OpenAPI specification, but can also be utilized
in other use cases as well.

## Custom Types

To gain access to the static type information of your custom types at runtime, the
easiest way is to use the derive macro:

```rust
#[derive(OpenapiType)]
struct FooBar {
	foo: Option<String>,
	bar: u64
}
```

## OpenAPI specification

Using above type, running `FooBar::schema().into_schema()` yields

```yaml
properties:
  foo:
    type: string
  bar:
    type: integer
    minimum: 0
    format: int64
type: object
required:
  - bar
title: FooBar

```

Note, however, that this is not sufficient for more complex types. If one of your
structs fields is a type that has a name (that is, `Type::schema().name` is not
`None`), above schema will contain a reference to that schema. Therefore, always
remember to put the [`dependencies`][__link4] into the
specification alongside the type you are interested in.

### Path Parameters

We can also treat the `FooBar` struct from above as a struct containing path
parameters, if we construct an [`Operation`][__link5] for a path like
`/foo/{foo}/bar/{bar}`. Running `FooBar::path_params()` yields

```yaml
- name: foo
  in: path
  required: true
  schema:
    type:
      - string
      - "null"
- name: bar
  in: path
  required: true
  schema:
    type: integer
    minimum: 0
    format: int64

```

### Query Parameters

Likewise, we can treat the `FooBar` struct from above as a struct containing query
parameters. Running `FooBar::query_params()` yields

```yaml
- name: foo
  in: query
  required: false
  allowEmptyValue: true
  schema:
    type: string
- name: bar
  in: query
  required: true
  schema:
    type: integer
    minimum: 0
    format: int64

```

## Features

The following cargo features may be enabled for this crate to unlock additional
implementations for larger tuples. For example, the `tuples32` feature would unlock
the implementation for tuples with sizes up to 32.

* `tuples16` (enabled by default)
* `tuples32`
* `tuples48`
* `tuples64`

The following cargo features may be enabled for this crate to unlock additional
implementations for external crates:

* `chrono`: Enable all of the below:
  * `chrono04`: Enable implementations for [`chrono` 0.4][__link6]
* `hashbrown`: Enable all of the below:
  * `hashbrown016`: Enable implementations for [`hashbrown` 0.16][__link7]
  * `hashbrown017`: Enable implementations for [`hashbrown` 0.17][__link8]
* `jiff`: Enable all of the below:
  * `jiff02`: Enable implementations for [`jiff` 0.2][__link9]
* `linked-hash-map`: Enable all of the below:
  * `linked-hash-map05`: Enable implementations for [`linked-hash-map` 0.5][__link10]
* `time`: Enable all of the below:
  * `time03`: Enable implementations for [`time` 0.3][__link11]
* `url`: Enable all of the below:
  * `url2`: Enable implementations for [`url` 2.x][__link12]
* `uuid`: Enable all of the below:
  * `uuid1`: Enable implementations for [`uuid` 1.x][__link13]

Note that support for [`indexmap` 2.x][__link14] is enabled by default.


## Versioning

Like all rust crates, this crate will follow semantic versioning guidelines. However, changing
the MSRV (minimum supported rust version) is not considered a breaking change.

## License

Copyright (C) 2021-2026 Dominic Meiser and [contributors].

```
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

	https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
```

 [contributors]: https://codeberg.org/msrd0/openapi_type/activity/contributors
 [__cargo_doc2readme_dependencies_info]: ggGmYW0CYXZlMC43LjNhdIQbJRDrHjphsUEbWo_vp8m3syobDYTsPTDgvvQbjC9yqPfAn7thYvRhcoQb-kNFgb42gU8bmW-i45GYayEbZqEzI-UC8KQbxPQ20x7tob9hZIuDZmNocm9ub2YwLjQuNDVoY2hyb25vMDSDaWhhc2hicm93bmYwLjE2LjFsaGFzaGJyb3duMDE2g2loYXNoYnJvd25mMC4xNy4xbGhhc2hicm93bjAxN4JoaW5kZXhtYXBmMi4xNC4wg2RqaWZmZjAuMi4yOGZqaWZmMDKDb2xpbmtlZC1oYXNoLW1hcGUwLjUuNnFsaW5rZWRfaGFzaF9tYXAwNYJkb2FzM2YwLjIyLjCCbG9wZW5hcGlfdHlwZWUwLjYuMINkdGltZWYwLjMuNDlmdGltZTAzg2N1cmxlMi41LjhkdXJsMoNkdXVpZGYxLjIzLjNldXVpZDE
 [__link0]: https://docs.rs/crate/openapi_type/latest/source/Cargo.toml.orig
 [__link1]: https://docs.rs/openapi_type/0.6.0/openapi_type/trait.OpenapiType.html
 [__link10]: https://crates.io/crates/linked-hash-map/0.5.6
 [__link11]: https://crates.io/crates/time/0.3.49
 [__link12]: https://crates.io/crates/url/2.5.8
 [__link13]: https://crates.io/crates/uuid/1.23.3
 [__link14]: https://crates.io/crates/indexmap/2.14.0
 [__link2]: https://docs.rs/openapi_type/0.6.0/openapi_type/?search=OpenapiType::schema
 [__link3]: https://docs.rs/openapi_type/0.6.0/openapi_type/?search=OpenapiSchema
 [__link4]: https://docs.rs/openapi_type/0.6.0/openapi_type/?search=OpenapiSchema::dependencies
 [__link5]: https://docs.rs/oas3/0.22.0/oas3/?search=spec::Operation
 [__link6]: https://crates.io/crates/chrono/0.4.45
 [__link7]: https://crates.io/crates/hashbrown/0.16.1
 [__link8]: https://crates.io/crates/hashbrown/0.17.1
 [__link9]: https://crates.io/crates/jiff/0.2.28