Beginnen Sie noch heute mit GraphQL, indem Sie Ihr Swagger-Schema konvertieren

Mit Swagger-to-graphql können Sie aus einem Swagger (OpenAPI)-Schema ein GraphQL-Schema erzeugen. Damit müssen Sie kein GraphQL-Schema programmieren, so dass Sie schnell mit GraphQL loslegen können. Es kann in Ihrem Rechenzentrum unter Verwendung von NodeJS ausgeführt werden, aber es läuft auch im Browser, um zu experimentieren. Das heißt, Sie können es online mit Ihrem eigenen Schema ausprobieren. Es gibt auch öffentliche Swagger-Schemata im APIs.guru OpenAPI-Verzeichnis.

Warum swagger-to-graphql?

Swagger-to-graphql ist bereit für den Einsatz in der Produktion, aber es ist auch ideal für schnelle Experimente. Wenn Sie es im Browser ausführen, können Sie mit GraphQL experimentieren, ohne im Backend kodieren zu müssen. GraphQL-Aufrufe werden in Ajax-Aufrufe umgewandelt. Beachten Sie, dass Sie GraphQL für den produktiven Einsatz in Ihrem Rechenzentrum ausführen sollten. Wenn Sie GraphQL im Browser ausführen, liefern Sie einen Parser und Interpreter aus. Außerdem erhalten Sie nicht die effiziente Datenabfrage von GraphQL.

[caption id="attachment_27624" align="aligncenter" width="480"] GraphQL-Aufrufe werden in Ajax-Aufrufe im Browser übersetzt[/caption]

Um alle Vorteile von GraphQL zu nutzen, führen Sie swagger-to-graphql in Ihrem Rechenzentrum aus. Wenn Sie Ihre bestehende REST-API weiterhin offenlegen, erhalten Sie eine hybride API mit REST und GraphQL. Dies kann ein Schritt in einem Migrationsplan zu vollständigem GraphQL sein oder Sie können diesen hybriden Ansatz langfristig beibehalten.

[caption id="attachment_27632" align="aligncenter" width="351"] In der Produktion ist swagger-to-graphql eine Middleware-Schicht[/caption]

Wenn Sie in der Produktion arbeiten, möchten Sie die volle Kontrolle darüber haben, wie die API-Aufrufe erfolgen. Aus diesem Grund führt swagger-to-graphql selbst keine Datenabrufe durch. Sie stellen den API-Client bereit und führen den eigentlichen Aufruf durch. So können Sie auswählen, welche HTTP-Header an das Backend weitergeleitet werden, wie die Abfrageparameter serialisiert werden und welcher Verbindungspool verwendet wird. Um schnell loszulegen, können Sie eine der mitgelieferten Beispielimplementierungen kopieren/einfügen. Vor kurzem habe ich einen großen Teil von swagger-to-graphql umgeschrieben, um es produktionsreif zu machen. Der Code wurde für eine bessere Lesbarkeit überarbeitet, in TypeScript konvertiert und hat eine gute Testabdeckung. Das macht es einfacher, Verbesserungen beizutragen, was die Langlebigkeit des Projekts gewährleistet.

Wie fangen Sie an?

Um loszulegen, müssen Sie swagger-to-graphql auf Ihr Swagger-Schema verweisen und einen Callback bereitstellen, der den Datenabruf durchführt. Sie erhalten dann ein GraphQL-Schema, das REST-Aufrufe tätigen kann. Der Datenabruf-Callback wird mit den Daten aufgerufen, die Sie für einen REST-Aufruf benötigen.

// requestOptions:
{
  Methode: 'post',
  baseUrl: 'https://petstore.swagger.io/v2',
  Pfad: '/pet',
  bodyType: 'json',
  Körper: { name: 'neuer Hund' },
  Kopfzeilen: {
  api_key: '1234',
  },
};

Im Browser kann dies an einen Fetch-Aufruf übergeben werden. Auf dem Server können Sie node-fetch oder einen anderen HTTP-Client verwenden.

importieren { createSchema, CallBackendArguments } von 'swagger-to-graphql';
async Funktion callBackend({
  requestOptions: { method, body, baseUrl, path, query, headers },
}: CallBackendArguments<{}>) {
  const url = `${baseUrl}${path}?${new URLSearchParams(query as Record<
  String,
  String
  >)}`;
  const response = await fetch(url, {
  Methode,
  Kopfzeilen: {
  Content-Type': 'application/json',
  ...Kopfzeilen,
  },
  Körper: JSON.stringify(body),
  });
  const text = await response.text();
  wenn (200  <= response.status && response.status  <  300) {
  versuchen {
  return JSON.parse(text);
  } catch (e) {
  Text zurückgeben;
  }
  }
  throw new Error(Response: ${response.status} - ${text});
}
const schemaPromise = createSchema({
  swaggerSchema: 'https://my-origin.com/myservice/swagger.json',
  callBackend,
});

Beachten Sie, dass in diesem Beispiel nur JSON-Payloads unterstützt werden. Swagger-to-graphql unterstützt auch formularcodierte Daten. Das Beispiel node-fetch auf Github zeigt, wie Sie dies implementieren.

Code-Erstellung mit Apollo

Der Apollo GraphQL-Client kann Typen auf der Grundlage von Abfragen in Ihrem Frontend-Code erzeugen. Das bedeutet, dass Sie eine durchgängige Typensicherheit erhalten. Vor allem, wenn Ihr Swagger-Schema durch den Backend-Code generiert wurde oder wenn Ihr Backend-Code durch Ihr Swagger-Schema generiert wird. Beide Ansätze stellen sicher, dass das Backend und das Frontend dasselbe Datenmodell einhalten müssen. Um Typen zu generieren, benötigt Apollo CLI ein GraphQL-Schema. Normalerweise lädt Apollo dieses Schema mit Hilfe einer Introspektionsabfrage von einem laufenden GraphQL-Server herunter. Wenn Sie Ihren Server noch nicht im Einsatz haben, können Sie auch ein Schema auf der Grundlage der Swagger-Datei generieren. Swagger-to-graphql bietet ein CLI-Tool, das aus einer Swagger-Datei ein GraphQL-Schema erzeugt. Sie können NPM-Skripte konfigurieren, um das Schema und die Typen zu erzeugen.

"Skripte": {
  "generate-schema": "swagger-to-graphql --swagger-schema https://petstore.swagger.io/v2/swagger.json > src/__generated__/schema.graphql",
  "precodegen": "npm run generate-schema",
  "codegen": "apollo client:codegen --target typescript"
},

Damit dies funktioniert, müssen Sie außerdem eine Konfigurationsdatei hinzufügen, um Apollo mitzuteilen, wo es das GraphQL-Schema finden kann. Da sich die Datei schema.graphql im Ordner src/ befindet, muss sie ausgeschlossen werden, da die Codegenerierung sie sonst doppelt interpretiert und einen Fehler ausgibt.

// apollo.config.js
module.exports = {
  Client: {
  Dienst: {
  Name: 'petstore',
  localSchemaFile: 'src/__generated__/schema.graphql'
  },
  schließt aus: ['src/__generated__/schema.graphql']
  }
};

Damit Apollo mit dem von swagger-to-graphql generierten Schema im Browser arbeiten kann, müssen Sie apollo-link-schema verwenden. Damit werden Abfragen unter Verwendung des generierten GraphQL-Schemas ausgeführt, während die Standardkonfiguration von Apollo einen entfernten GraphQL-Server voraussetzt.

import { ApolloClient } from 'apollo-client';
import { InMemoryCache } from 'apollo-cache-inmemory';
import SchemaLink from 'apollo-link-schema';
function createApolloClient(schema: GraphQLSchema) {
  return new ApolloClient({
  cache: new InMemoryCache(),
  link: new SchemaLink({
  schema,
  }),
  });
}

Holen Sie sich den Beispielcode!

Ein voll funktionsfähiges Beispiel ist auf Github verfügbar. Sie können es auch online ausprobieren, um zu sehen, wie die Ajax-Aufrufe im Browser ausgeführt werden.

Nächste Schritte

Jetzt, wo Sie ein automatisch generiertes GraphQL-Schema haben, möchten Sie vielleicht dessen Aussehen verbessern. Der beste Ansatz ist, das Swagger-Schema zu verbessern, was wiederum das GraphQL-Schema verbessert. Wenn Sie mehr Kontrolle benötigen, können Sie sich die GraphQL-Schema-Transformationen ansehen. Damit können Sie jeden Teil Ihres GraphQL-Schemas ändern und gleichzeitig Swagger-to-Graphql und die verwendete REST-API nutzen. Irgendwann werden Sie Ihr gesamtes Unternehmen auf GraphQL umstellen wollen, was bedeutet, dass Sie mehrere Backends aus verschiedenen Teams in einem einzigen GraphQL-Endpunkt zusammenfassen wollen. Das ist schneller als die Abfrage mehrerer GraphQL-Endpunkte, weil Sie nur eine einzige Anfrage stellen müssen, um alle Daten abzurufen. Dazu können Sie GraphQL Schema Stitching verwenden. Sie können sogar verschachtelte Verknüpfungen verschiedener GraphQL-Resolver durchführen. Auf diese Weise können Sie mit einem einzigen API-Aufruf mehr Daten abrufen. Beachten Sie, dass Sie die Logik für diese Verknüpfungen in dem verknüpfenden GraphQL-Dienst konfigurieren müssen. Dies könnte dazu führen, dass Ihre Teams weniger autonom sind. Ein neuer Ansatz zur Kombination von GraphQL-Schemata ist die GraphQL-Föderation. Sie verfolgt das gleiche Ziel wie Schema Stitching, aber sie konfiguriert die Verknüpfung nicht im zentralen Gateway, sondern in den verteilten GraphQL-Schemas selbst. Leider wird dies von swagger-to-graphql noch nicht unterstützt. Ich denke darüber nach, eine GraphQL-Schema-Transformation zu erstellen, die jedem GraphQL-Schema Federation hinzufügt, aber ich muss noch Code schreiben, damit das funktioniert. Bleiben Sie also dran!