OpenAPITools / OpenAPITools/openapi-generator
[REQ] consistent path formats in generated outputs for linux and windows
Nobody has claimed this yet.
- Dominant language
- Java
- Stars
- 26.8k
- Forks
- 7.7k
- PR merge metrics
- PR metrics pending
Description
Background for the issue
Running
openapi-generator generate \
--skip-validate-spec \
--input-spec "schemas/algorithms.yaml" \
--generator-name markdown \
--output "docs/@api/algorithms"
on e.g.
# schemas/algorithms.yaml
openapi: 3.0.3
info:
version: 0.0.0
title: "Test models"
servers:
- url: "https://myapi.acme.org"
paths: {}
components:
schemas:
AlgorithmModes:
type: string
enum:
- RANDOM
- GRADIENT
- DEFAULT
yields the files
docs
├── @api
│ ├── algorithms
│ │ ├── Models
│ │ │ ├── AlgorithmModes.md
│ │ └── README.md
where the README.md file looks like
# Documentation for Test models
<a name="documentation-for-api-endpoints"></a>
## Documentation for API Endpoints
All URIs are relative to *https://myapi.acme.org*
Class | Method | HTTP request | Description
------------ | ------------- | ------------- | -------------
<a name="documentation-for-models"></a>
## Documentation for Models
- [ClientConfig](.//Models/AlgorithmModes.md)
<a name="documentation-for-authorization"></a>
## Documentation for Authorization
All endpoints do not require authorization.
The issue
The issue is that the this output is generated in a way that depends on the operating system. The link
.//Models/AlgorithmModes.md
is generated with the standard path separator (.//) when running on linux/osx. But when running on windows, the non-standard ./\ path separator is used.
This is particularly irksome when using this tool in a repository maintained by multiple developers some on windows, some on linux/osx.
Describe the solution you'd like
Either forcibly ensure that .// is always used. Or provide a new flag, e.g.
--path-root-format [linux|windows|system]
# linux: uses ".//" regardless of the system on which the tool is run
# windows: uses "./\" regardless of the system on which the tool is run
# system: uses ".//" or "./\" dependent upon the system on which the tool is run
for backwards compatibility, one could make --path-root-format system the default, but even here it may be better to make --path-root-format linux the default option.
Describe alternatives you've considered
Find and replace, which is a tad tedious and impossible to enforce in a team of developers.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reproducing the openapi-generator generate command with schemas/algorithms.yaml and the markdown generator on Linux and Windows, then trace how docs/@api/algorithms/README.md builds the Models link. Done means the generated link format is consistent across operating systems, with the compatibility/default behavior decided and covered by a regression test.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java, openapi
- Domain
- build-system, documentation
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100