Oaskit provides an agent skill that migrates a Phoenix application from OpenApiSpex to
Oaskit and JSV:
migrate-openapispex-to-oaskit.
The skill guides a coding agent through the whole migration, from an inventory of the application to a passing test suite. Scripts do the mechanical rewrites of schemas, controllers and tests, and the agent handles the remaining cases with the skill's references. At the end, the agent compares the OpenAPI documents generated before and after the migration.
The references in the references directory of the skill map OpenApiSpex features to
Oaskit and JSV. They are also useful to migrate without an agent.
Installing the skill
With the skills CLI:
npx skills add lud/oaskit --skill migrate-openapispex-to-oaskit
Or copy the skills/migrate-openapispex-to-oaskit directory of this repository to the
skills directory of your agent.
The agent will modify many files, so starting from a clean working tree makes its changes easier to follow.
Decisions for your API clients
The migration changes some parts of the API that clients can see. The skill leaves those choices to you. Select your answers below, and the example prompt at the end of this page will follow them.
Validation error responses
OpenApiSpex answered validation errors with a 422 status and a list of errors. Oaskit uses a different body, and the 400, 415 or 422 status depending on the error.
Operation IDs in the OpenAPI document
For operations without an explicit operation_id, Oaskit generates different operationIds
than OpenApiSpex. Clients and tools generated from the OpenAPI document use them.
Schema names in the OpenAPI document
OpenApiSpex named schemas without a title after the last segment of their module (User),
Oaskit uses the full module name (MyApp.Schemas.User).
String format validation
JSV validates formats that OpenApiSpex ignored, such as email, uri or hostname.
Required request bodies
OpenApiSpex request bodies declared as {description, content_type, schema}
were optional. The skill rewrites them with the short form of Oaskit
(request_body: UserSchema), which makes the body required. With a full
request body declaration, required defaults to false as in OpenAPI.
Example prompt
Add your own instructions to this prompt, for instance how the agent should use git.
Migrate this app from OpenApiSpex to Oaskit with the migrate-openapispex-to-oaskit skill, through all its phases.
Decisions for phase 0:
- Error responses: use the bridge handler, with the old 422 status.
- Operation ids: pin them.
- Component names: keep them (--titles). When several schema modules share a title, keep it on the module the old document used.
- Formats: keep JSV's format validation, and update the tests that expected the error from the action.
- Request bodies: required, except where an endpoint accepts an empty body.The skill makes the agent write migration notes outside of the project, in an
OASKIT_MIGRATION.md file: the decisions, the test results before the migration, the
tests removed and why, and what changes for API clients. The agent gives you the path of
that file at the end of the migration.