OpenAPITools / OpenAPITools/openapi-generator

[REQ] consistent path formats in generated outputs for linux and windows

Open
#19,531 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Enhancement: Feature
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.