Rust OpenAPI 3.0 docs generator
Or see more here
```rust use opg::*; use serde::{Serialize, Deserialize};
enum SimpleEnum { Test, Another, Yay, }
struct NewType(String);
struct SimpleStruct { first_field: i32, #[opg("Field description")] second: String, }
enum ExternallyTaggedEnum { Test(String), AnotherTest(String, #[opg("Second")] String), }
enum UntaggedEnum { First { value: NewType, }, #[opg("Variant description")] Second { #[opg("Inlined struct", inline)] another: SimpleStruct, }, }
enum InternallyTaggedEnum { First(SimpleStruct), Second { field: String }, }
enum AdjacentlyTaggedEnum { First(String), Second(NewType, NewType), }
struct TypeChangedStruct { #[serde(with = "chrono::naive::serde::ts_milliseconds")] #[opg("UTC timestamp in milliseconds", integer, format = "int64")] pub timestamp: chrono::NaiveDateTime, }
struct StructWithComplexObjects {
#[serde(skipserializingif = "Option::isnone")]
#[opg(optional)]
superoptional: Option
struct GenericStructWithRef<'a, T> { message: &'a str, test: T, }
struct SuperResponse { simpleenum: SimpleEnum, #[serde(rename = "newtype")] newtype: NewType, externallytaggedenum: ExternallyTaggedEnum, untaggedenum: UntaggedEnum, internallytaggedenum: InternallyTaggedEnum, adjacentlytaggedenum: AdjacentlyTaggedEnum, typechangedstruct: TypeChangedStruct, structwithcomplexobjects: StructWithComplexObjects, }
fn printapi() {
let test = describeapi! {
info: {
title: "My super API",
version: "0.0.0",
},
tags: {internal, admin("Super admin methods")},
servers: {
"https://my.super.server.com/v1",
},
securityschemes: {
(http "bearerAuth"): {
scheme: Bearer,
bearerformat: "JWT",
},
},
paths: {
("hello" / "world" / { paramTest: String }): {
summary: "Some test group of requests",
description: "Another test description",
parameters: {
(header "x-request-id"): {
description: "Test",
required: true,
},
},
GET: {
tags: {internal},
summary: "Small summary",
description: "Small description",
deprecated: true,
parameters: {
(query someParam: u32): {
description: "Test",
}
},
200: String,
418 ("Optional response description"): String
},
POST: {
tags: {admin},
security: {"bearerAuth"},
body: {
description: "Some interesting description",
schema: GenericStructWithRef<'static, i64>,
required: true,
},
200: SuperResponse,
callbacks: {
callbackUrl: {
("callbackUrl"): {
POST: {
200: std::vec::Vec
println!("{}", serde_yaml::to_string(&test).unwrap());
} ```
Result:
```yaml --- openapi: 3.0.3 info: title: My super API version: 0.0.0 tags: - name: admin description: Super admin methods - name: internal servers: - url: "https://my.super.server.com/v1" paths: "/hello/world/{paramTest}": summary: Some test group of requests description: Another test description get: tags: - internal summary: Small summary description: Small description deprecated: true responses: 200: description: OK content: application/json: schema: type: string 418: description: Optional response description content: application/json: schema: type: string parameters: - name: someParam description: Test in: query schema: type: integer format: uint32 post: tags: - admin security: - bearerAuth: [] requestBody: required: true description: Some interesting description content: application/json: schema: $ref: "#/components/schemas/GenericStructWithRef" responses: 200: description: OK content: application/json: schema: $ref: "#/components/schemas/SuperResponse" callbacks: callbackUrl: /callbackUrl: post: responses: 200: description: OK content: application/json: schema: type: array items: type: string parameters: - name: paramTest in: path required: true schema: type: string - name: x-request-id description: Test in: header required: true schema: type: string components: schemas: AdjacentlyTaggedEnum: type: object properties: content: oneOf: - type: string - type: array items: oneOf: - $ref: "#/components/schemas/NewType" - $ref: "#/components/schemas/NewType" tag: description: AdjacentlyTaggedEnum type variant type: string enum: - first - second example: first required: - tag - content ExternallyTaggedEnum: type: object additionalProperties: oneOf: - type: string - type: array items: oneOf: - type: string - description: Second type: string GenericStructWithRef: type: object properties: message: type: string test: type: integer format: int64 required: - message - test InternallyTaggedEnum: oneOf: - type: object properties: first_field: type: integer format: int32 second: description: Field description type: string tag: description: InternallyTaggedEnum type variant type: string enum: - first example: first required: - first_field - second - tag - type: object properties: field: type: string tag: description: InternallyTaggedEnum type variant type: string enum: - second example: second required: - field - tag NewType: description: newtype string type: string format: id example: abcd0001 SimpleEnum: description: Simple enum type: string enum: - test - another - yay example: test StructWithComplexObjects: type: object properties: boxed: nullable: true type: integer format: int32 field: nullable: true type: string super_optional: nullable: true type: string required: - field - boxed SuperResponse: type: object properties: adjacently_tagged_enum: $ref: "#/components/schemas/AdjacentlyTaggedEnum" externally_tagged_enum: $ref: "#/components/schemas/ExternallyTaggedEnum" internally_tagged_enum: $ref: "#/components/schemas/InternallyTaggedEnum" new_type: $ref: "#/components/schemas/NewType" simple_enum: $ref: "#/components/schemas/SimpleEnum" struct_with_complex_objects: $ref: "#/components/schemas/StructWithComplexObjects" type_changed_struct: $ref: "#/components/schemas/TypeChangedStruct" untagged_enum: $ref: "#/components/schemas/UntaggedEnum" required: - simple_enum - new_type - externally_tagged_enum - untagged_enum - internally_tagged_enum - adjacently_tagged_enum - type_changed_struct - struct_with_complex_objects TypeChangedStruct: type: object properties: timestamp: description: UTC timestamp in milliseconds type: integer format: int64 required: - timestamp UntaggedEnum: oneOf: - type: object properties: value: $ref: "#/components/schemas/NewType" required: - value - description: Variant description type: object properties: another: description: Inlined struct type: object properties: first_field: type: integer format: int32 second: description: Field description type: string required: - first_field - second required: - another securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ```