Problem/Motivation

A site installed with this site template comes up with a working API and nothing that says so. There is no page explaining what the API serves, where to start reading it, or where the documentation lives.

There is also no content type to build a page with. This template applies core/recipes/standard, which brings Article and Page, but not the webpage type the other Webship templates use with Display Builder.

Proposed resolution

  • Apply modules/contrib/webpage/recipes/default first, for the webpage content type, Display Builder and the editorial workflow.
  • Ship a content/ directory with one page and its path alias, describing the API and how to read it.

The page is written for this template rather than copied from the Webships Starter. That template's equivalent page links to /api/node/webapp and /api/node/organization, which do not exist here: this template has no gallery content model. This page points at /api, the resource list, and explains that every content type the site owner adds appears there.

Steps to reproduce

  1. Build a project with the Webships installer and choose this site template.
  2. Visit the front page of the finished site.
  3. The API works, but nothing on the site describes it.

Remaining tasks

  • ✅ Write the page for this template and open a merge request
  • ❌ Install a site from this branch and check the page
  • ❌ Reviewed by the maintainer

Merge request

Merge request !2 against 1.0.x.

Worth deciding

The page describes the Swagger UI rather than linking to it. That route is /admin/config/services/openapi, behind the access openapi api docs permission, which anonymous does not hold. Granting it to anonymous would allow a public documentation link.

AI-Generated: Yes

Comments

rajab natshah created an issue. See original summary.

rajab natshah’s picture

rajab natshah
he/him
commented
Title: Ship a front page describing the API and its documentation » Blank values in fully validatable configuration stop the site template applying to a clean site
Category: Feature request » Bug report
Issue summary: View changes
Priority: Normal » Major

The merge request now applies to a genuinely clean site. Verified by installing a minimal site that had never seen this recipe, then applying the branch recipe once:

Applied Web API - Default recipe.
Applied WebAPI Starter recipe.
[OK] WebAPI Starter applied successfully
RECIPE APPLY EXIT CODE: 0

What the recipe created:

  • Content type: node.type.webpage
  • Content: the page The API and its documentation, published

One defect was found and fixed on the branch while getting there: an exported path_alias entity that hard coded a node id from the site it was exported from (/node/1). The page node already carries its own alias in its path field, so the separate alias entity was both redundant and unportable. It has been removed.

AI-Generated: Yes

rajab natshah’s picture

rajab natshah
he/him
commented
Status: Active » Fixed

Merged to 1.0.x.

Verified on the merged branch: the template ships the API documentation page and applies to a site that has never seen it.

AI-Generated: Yes

Now that this issue is closed, review the contribution record.

As a contributor, attribute any organization that helped you, or if you volunteered your own time.

Maintainers, credit people who helped resolve this issue.