The purpose of this library is to expose the generation of file with open api specifications from your shelf controllers OpenApi Specification
This library is under development, any help is welcome
- Info (Versioning, EndPoint and more api info)
- Params (Supported only string type params)
- Requests
- Responses
- Bad Responses
- Reused schemas by
$ref - Inheritance and Polymorphism by
allOf,oneOf,anyOf,discriminator -
json_serializableannotations - [-] Security (Partial implemented)
- Docs (
summary,description,example) - Tags/Groups
- Deprecated operations by
@Deprecated()meta annotation - Default values
default
To use shelf_open_api, you will need your typical build_runner/code-generator setup. First, install build_runner, shelf_open_api, shelf_open_api_generator by adding them to your pubspec.yaml file:
# pubspec.yaml
dependencies:
shelf_open_api:
dev_dependencies:
build_runner:
shelf_open_api_generator:You can see some examples in example folder.
Run the code generator, you can use:
<dart|flutter> pub run build_runner build
You can see the generated result in the public folder!
Done! See options for more info/configurations. But now let's type the routes!
Use OpenApiRoute on routes where the query type or body type needs to be defined.
Remember that you can define the summary and description for each route.
The summary is the first line of each method and must only be in one line otherwise it will be a description of your route.
The JsonResponse class can be found in the example. Should I add it to shelf_open_api package?
class MessagesController {
@Route.get('/messages')
@OpenApiRoute(requestQuery: MessageFetchDto)
Future<JsonResponse<void>> fetch(Request request) async {
// Code...
}
/// This is a summary
///
/// This is a
/// long description
@Route.post('/messages')
@OpenApiRoute(requestBody: MessageCreateDto)
Future<JsonResponse<void>> create(Request request) async {
// Code...
}
}You can define summaries, descriptions and examples for your queries or requests as well
class MessageCreateDto {
/// The id of the chat where the message will be sent
final String chatId;
/// The content of the message.
///
/// You can enter texts and emojis. Images are not supported.
///
/// `Hi, Luigi!`
final String content;
const MessageCreateDto({
required this.chatId,
required this.content,
});
}You can find many other configuration parameters by looking at the config file.
targets:
$default:
builders:
shelf_open_api_generator:
options:
include_routes_in: 'lib/**_controller.dart'
info_title: 'Api'
security_schemes:
appwriteJwt:
type: http
scheme: Bearer
bearerFormat: JWTHave too many controllers in your app? This could save you!
Write something down with Routing and a file with all the controllers in your app will be generated!
@Routing(
varName: 'controllersRouter',
generateFor: ['**/*_controller.dart'],
)
void main() {
// ...
}
// *.g.dart
import 'package:shelf_router/shelf_router.dart';
import 'package:app/features/chats/controllers/chats_controller.dart';
import 'package:app/features/messages/controllers/messages_controller.dart';
import 'package:app/features/users/controllers/users_controller.dart';
final $controllersRouter = Router()
..mount('/v1', UsersController().router)
..mount('/v1', MessagessController().router)
..mount('/v1', ChatsController().router);This allows you to annotate your controllers with @Routes(prefix: '/v1') to prefix all controller routes.
This annotation is not mandatory!
@Routes(prefix: '/v1')
class MessagesController {
// ...
}targets:
$default:
builders:
shelf_open_api_generator:shelf_routing:
generate_for:
- '**/*_api.dart'open_api_client_generator The purpose of this library is to expose the generation of file with open api specifications from your shelf controllers
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent