Migrate from gisila

You will switch a plain gisila app to gisila_doc. Runtime behaviour stays the same, since both generate routes through gisilaRoute; what you gain is an OpenApiSpec and the docs UI.

Prerequisites

• A gisila app with @Controller classes and generated attachToApp methods.
• gisila >=0.3.0 <0.5.0 (what gisila_doc 0.3.1 accepts).

Steps

1. Swap the dependency

dependencies:
  gisila_doc: ^0.3.1   # brings gisila in transitively
  shelf: ^1.4.1
  shelf_router: ^1.1.4

dev_dependencies:
  build_runner: ^2.5.0

You can keep a direct gisila dependency if other code imports it, but see step 2: a controller file must not import both packages unprefixed.

Caution

If gisila stays a direct dependency, its builder also auto-applies to your package. Each builder only acts on its own annotations, so controllers converted to gisila_doc’s annotations are not picked up twice.

2. Change the import in each controller

import 'package:gisila/gisila.dart';
import 'package:gisila_doc/gisila_doc.dart';

gisila_doc re-exports gisila except for the annotation names it redefines (Controller, Route, Get … Options, Body, Query, Path, Header). Guards, RouteConfig, UseRouteConfig, UseMiddleware, Form, Service, RequestContext and GisilaApp are the same classes.

3. Review annotation arguments

gisila	gisila_doc	Action
@Controller('/users')	@Controller('/users', ['Users'])	Optionally add tags.
@Get('/x', statusCode: ..., config: ...)	same, plus summary, description, operationId, deprecated, tags, body, responses	Add documentation fields.
@Get('/x', contentType: 'text/plain')	no contentType parameter	Remove it. Return a Response with the content type you need, and document it with @Returns.
@Query(name: 'q'), @Path(name: ...), @Header(name: ...)	same, plus description	No change needed.
@Body()	same	No change needed.

4. Pass a spec to attachToApp

The generated method gains a spec parameter:

final spec = OpenApiSpec(info: const ApiInfo(title: 'My API', version: '1.0.0'));

app.registerController(
  attacher: (app, router, {String prefix = ''}) =>
      UsersController().attachToApp(app, router, prefix: prefix),
  attacher: (app, router, {String prefix = ''}) {
    UsersController().attachToApp(app, router, spec, prefix: prefix);
    router.mount('/', docsHandler(spec));
  },
);

5. Regenerate

dart run build_runner build --delete-conflicting-outputs

The .g.dart file now contains a UsersControllerGisilaDoc extension instead of gisila’s.

6. Fill in documentation

Add summary, operationId and @ApiResponse entries where they help. Routes that return a raw Response need @Returns(bodyType: ...) to show a response schema; see Describe request and response models.

Upgrading from gisila_doc 0.1.x

If you are on an older gisila_doc, the generated method used to be attachOpenApi(spec, router). Replace those calls with attachToApp(app, router, spec, {prefix}), start the server with GisilaApp.start(...) instead of shelf_io.serve, and register services with app.registerService<T>(T.new).

Verify it works

• Your existing tests pass unchanged; status codes and error bodies are produced by the same gisila runtime.
• curl -s localhost:8080/openapi.json | jq '.paths | keys' lists every route.

Next steps

• Document an API for a full walkthrough.
• gisila_doc or gisila?