adobe / adobe/jsonschema2md

Unable to resolve locally available schemas

Open
#179 2 comments 7 reactions 0 assignees View on GitHub
Dominant language
JavaScript
Stars
724
Forks
150
Avg merge
18h 22m
Merged PRs (30d)
4

Description

## What did you do

I've taken this project:
https://github.com/maasglobal/maas-schemas

And I trying to generate documentation by running
```
npm install @adobe/jsonschema2md
yarn jsonschema2md -d schemas -e json -e o docs
```

## What did you expect to happen

- [x] All schema documentation generated in docs
- [ ] All internal links resolved properly

## What happened

- All schema documentation generated in docs
- No links resolved between schemas
- Lots of warnings during generation, such as

```bash
unresolved reference: http://maasglobal.com/maas-backend/customers/payment-sources/paymentSource.json#/definitions/type
unresolved reference: #/definitions/acceptHeader
```

## What's your environment

* Operating System: Mac OS X 10.14.6
* node.js version: 12.11.1
* jsonschema2md version 3.3.1

## Do you have example files:

### Schemas in schemas/ folder
https://github.com/maasglobal/maas-schemas

### Markdown examples

#### Excerpt from core README.md
```markdown
## /tsp/booking-create/

- [](./tsp/booking-create/request.md) – `http://maasglobal.com/tsp/bookings-create/request.json` (Unknown)
- [](./tsp/booking-create/response.md) – `http://maasglobal.com/tsp/bookings-create/response.json` (Unknown)
```

#### Excerpt from core/booking-option.md
```markdown
...
## agencyId

`agencyId`

- is optional
- type: reference
- defined in this schema

### agencyId Type

- []() – `http://maasglobal.com/core/components/common.json#/definitions/agencyId`

...
```

Contributor guide

Open the contributing guide

Research direction

Reproduce the issue with the npm/yarn jsonschema2md command against the schemas/ folder, then compare the generated docs with the core README.md and core/booking-option.md examples. Trace how the locally available schema references are handled; done means internal links resolve and the unresolved-reference warnings no longer occur for the provided schemas.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.