Skip to content

Latest commit

 

History

History
132 lines (93 loc) · 3.64 KB

README.md

File metadata and controls

132 lines (93 loc) · 3.64 KB

CommonGrants core library

Code for the CommonGrants core specification library, written in TypeSpec. This library is designed to be imported and extended by individual implementations of the CommonGrants protocol.

🚀 Quickstart

Install the library

npm install @common-grants/core

Project setup

A basic project structure that uses the library might look like this:

.
├── models.tsp      # Extends @common-grants/core models with custom fields
├── routes.tsp      # Overrides @common-grants/core routes to use the custom models
├── main.tsp        # Defines an API service that uses the custom models and routes
|
├── tsp-output/     # Directory that stores the output of `tsp compile`, often .gitignored
|
├── package.json    # Manages dependencies, commands, and library metadata
└── tspconfig.yaml  # Manages TypeSpec configuration, including emitters

Define custom fields

The Opportunity model is templated to support custom fields. First define your custom fields by extending the CustomField model:

// models.tsp

import "@common-grants/core"; // Import the base specification library

// Allows us to use models and fields defined in the core library without
// prefixing each item with `CommonGrants.Models` or `CommonGrants.Fields`
using CommonGrants.Models;
using CommonGrants.Fields;

namespace CustomAPI.CustomModels;

// Define a custom field
model Agency extends CustomField {
  name: "Agency";
  type: CustomFieldType.string;

  @example("Department of Transportation")
  value: string;

  description: "The agency responsible for this opportunity";
}

// Extend the `OpportunityBase` model to create a new `CustomOpportunity` model
// that includes the new `Agency` field in its `customFields` property
model CustomOpportunity extends OpportunityBase {
  customFields: {
    agency: Agency;
  };
}

Override default routes

The router interfaces are templated to support your custom models. Override them like this:

// routes.tsp

import "@common-grants/core";
import "./models.tsp"; // Import the custom field and model from above

using CommonGrants.Routes;
using TypeSpec.Http;

@tag("Search")
@route("/common-grants/opportunities")
namespace CustomAPI.CustomRoutes {
  alias OpportunitiesRouter = Opportunities;

  // Use the default model for list but custom model for read and search
  op list is OpportunitiesRouter.list;
  op read is OpportunitiesRouter.read<CustomModels.CustomOpportunity>;
  op search is OpportunitiesRouter.search<CustomModels.CustomOpportunity>;
}

Define an API service

Next, use these updated routes to define an API service:

// main.tsp

import "@typespec/http";

import "./routes.tsp"; // Import the routes from above

using TypeSpec.Http;

/** Description of your API goes here */
@service({
  title: "Custom API",
})
namespace CustomAPI;

Generate the OpenAPI spec

Generate an OpenAPI specification from your main.tsp file using either the CLI:

npx tsp compile main.tsp --emit "@typespec/openapi3"

Or specify the emitter in tspconfig.yaml:

# tspconfig.yaml
emitters:
  - "@typespec/openapi3"

Both strategies will generate an OpenAPI specification in the tsp-output/ directory.

Further reading