#rocket #open-api #generate #cargo #path #parameters #rocketapi

yanked cargo-rocketapi

Rocket OpenApi (roapi) is a preliminary test in generating OpenApi files from a rocket project

1.0.0 Sep 5, 2019

#223 in #rocket

MIT license

51KB
1K SLoC

RocketAPI

First attempt to generate an OpenApi 3.0 yaml file from a project that contains rocket paths defined via the rocket proc_macros.

Usage

There are two possible ways to use roapi after installation:

cargo rocketapi

Will try to traverse the ./src folder for rust files and attempt to generate an OAS from those

cargo rocketapi filename

Will try to generate an OAS from one file

Cargo.toml Additions

You can specify custom servers in the Cargo.toml file by adding the following to your cargo.toml

[rocketapi]
servers = ["http://localhost:8000", "http://127.0.0.1:8000"]

Features

This is very much a WIP and will stay as such until I get help enough to make it more complete. For version 1.0, only project where every route is mounted at "/" and structures are globally unique will be handled.

Parsing mountpoints and determining entire paths and handling namespaces is unfortunately a bit out of my scope for v1.0. Help is always appreciated

Implemented:

- Find paths (does not handle the mountpount paths)
- Find input parameters for path and where they are located
- Use function comment as path comment
- Find type and limits for common input parameters (i8-u128,floats, doubles, strings)
- Find in all rust files under ./src
- Describe custom structures
- Option<types> to be marked as not required in spec
- Create a component tree from all the used structures
- Match component to parameter for special custom types
- Form<types> to be marked as formData
- Take project information from the Cargo file, and allow extra info in the cargo file for this
- Release 1.0 and maybe rename project to something better

Planned ( In order of probable implementation )

- Try to determine tags by filename the route was defined in
- Support Enums
- Support nested structs
- Try to determine outputs from a route
- Use rocket::mount to determine entire path

Installation

cargo install cargo-rocketapi

Dependencies

~12–22MB
~343K SLoC