Schema Editor

Italia OpenAPI Schema Editor is developed on Swagger Editor.

This repository uses PNPM and turborepo for packages management, and changesets for versioning and publishing.

Table of contents

• 💻 Usage
• 📋 Development
• 📝 Contributing
• ⚖️ License

Usage

Usage with Public Docker Image

To launch the application using the public docker image, run the following command:

docker run -d -p 8000:8000 ghcr.io/teamdigitale/dati-semantic-schema-editor:latest

or pick a specific version from the github container registry.

Usage with Docker

To launch the application, just run docker compose

• that will build and deploy the app - and open the browser

docker compose up -d app
open http://localhost:5000

Local Usage

To use the Semantic Schema Editor all you need to do is installing the @teamdigitale/schema-editor plugin and use the component in your application.

import 'bootstrap-italia/dist/css/bootstrap-italia.min.css';
import '@fontsource/lora';
import '@fontsource/roboto-mono';
import '@fontsource/titillium-web';

import './App.scss';

import { SchemaEditor } from '@teamdigitale/schema-editor';
import '@teamdigitale/schema-editor/dist/style.css';

function App() {
  const urlParams = new URLSearchParams(window.location.search);
  const schemaUrl = urlParams.get('url');

  return (
    <>
      <div className="app-container">
        <SchemaEditor
            url={schemaUrl}
            oasCheckerUrl={'https://italia.github.io/api-oas-checker/'}
            schemaEditorUrl={'Your URL here'}
        />
      </div>
    </>
  );
}

export default App;

This repository contains various usage examples:

• apps/example/src/App.tsx - Showcase webapp;
• apps/example/src/components/standalone - Standalone editor;
• apps/example/src/components/swaggerui-plugins-collection - Use the SwaggerUI component only.

Development

Develop with docker

To start the development environment with docker, run the following command:

docker compose up -d dev

This will run a development environment based on the dev.dockerfile and will start the development server.

Installation

Ensure to have installed PNPM package manager.

Install node modules by running

pnpm install

Running

Then simply execute

pnpm dev

to start all packages in development mode.

Versioning and publishing

When developing a new feature or performing a new bugfix the version of the package(s) must be increased. In order to process this correctly perform the following steps:

• Run pnpm changeset in the root of app in order to create a markdown containing the changes.

• Commit the generated files that are inside .changeset folder

• When the changesets files reach the "baseBranch" (actually "main"), a github action will generate a new PR with updated packages versions. Review the PR and approve merge when ready to release a new version.

• Once the PR is merged into the baseBranch, a github action will publish packages automatically.

• If you want to build and publish a pre-release version before going to the main branch, then rebase the "next" branch to the needed commit from main branch. The github action will open a new PR with the "-next.X" tag. Once merged in the "next" branch it will publish the package(s) as described above. For more informations and an example have a look at:

  • https://changesets-docs.vercel.app/en/prereleases
  • changesets/action#69 (comment)
  • statelyai/xstate#902

Pay attention: never merge "next" branch into "main"!

Docker builds

To create images for the two webapps, run th following commands:

# Editor webapp
docker build . --target webapp --tag webapp:latest

# Showcase webapp
docker build . --target example --tag example:latest

After creating the desired image, run it with the following command paying attention to change listening ports and config file if needed:

docker run -p 80:80 --mount type=bind,source=${PWD}/my-custom-config.js,target=/usr/share/nginx/html/config.js webapp:latest

Contributing

Please, see CONTRIBUTING.md for more details on:

• using pre-commit;
• following the git flow and making good pull requests.

License

BSD 3-Clause License © LICENSE