ePages-de / ePages-de/restdocs-api-spec

Fields order in OpenAPI Specification

Open
#198 3 comments 1 reaction 0 assignees View on GitHub
enhancement
Dominant language
Kotlin
Stars
427
Forks
116
Avg merge
23h 54m
Merged PRs (30d)
1

Description

Hi!

I have the next documentation section in my test:

```
...
.responseFields(
fieldWithPath("albums").description("Result list of requested albums"),
fieldWithPath("albums[].id").description("Album id, f.e. 59727856"),
fieldWithPath("albums[].barcodeId").description("Album's barcode id (EAN-13 or UPC-A)").optional(),
...
)
...
```

while OpenAPI Spec has the next relevant section:

```
...
components:
schemas:
albums629762604:
type: object
properties:
albums:
type: array
description: Result list of requested albums
items:
type: object
properties:
copyright:
type: string
description: Album's copyright information
releaseDate:
type: string
description: Album's release date (ISO-8601)
numberOfVolumes:
type: number
description: Number of volumes
...
...
```

which doesn't match the order in my test.

I do understand that from the structural point of view this is not a problem at all, but it is important when you trying to generate some static web pages based on Open API Spec. And there you may see fields in some non-logical order.

I do appreciate any feedback and your thoughts in this regard!

Thanks in advance!

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.