Swagger Specification Issues

[krowvin]

CWMSjs

Note package.json requires semantic numbering of the format (##.##.##). I can't put RC in the version

I'm working on releasing the next version of CWMSjs

To include all (most) of the new endpoints

Running the openapi generator for TypeScript and targeting the swagger.json spec json located here
gives a handful of errors (seen below)

I thought it would be worth bringing it up here especially if the java and jython generators have not been ran yet.

Background on how i'm getting the errors

TypeScript will do the type checking when you run tsc and transpile to JavaScript so that you don't have as many runtime errors in the browser (types/etc are checked on compile). Below is the output of that.

In some cases I was able to make the changes to the swagger schema and then run the generator + tsc again and the errors would be fixed. I believe this confirms it to be an issue with the swagger schema (annotations?)

Attempted error fixes to get the generation to complete

• Renaming all TimeSeries to Timeseries

  • Did a CTRL +F (case sensitive) TimeSeries and replace ALL with Timeseries
    • This removed all TS errors

• As for the remaining errors I tried doing the following:

  • Changed AbstractRatingMetadata > discriminator > propertyName from "rating-type" to "ratingType"
    • No Change to remaining errors

• Ended up removing all endpoints and references to the other errors for now.

Related to

• CDA JavaScript/TypeScript Client-Side SDK #351
• Add servers to the swagger docs for use with openapi generators #587

Error output running tsc against generated .ts files

src/apis/LevelsApi.ts:22:3 - error TS2724: '"../models/index"' has no exported member named 'TimeSeries'. Did you mean 'Timeseries'?

22   TimeSeries,
     ~~~~~~~~~~

src/apis/LevelsApi.ts:33:5 - error TS2724: '"../models/index"' has no exported member named 'TimeSeriesFromJSON'. Did you mean 'TimeseriesFromJSON'?

33     TimeSeriesFromJSON,
       ~~~~~~~~~~~~~~~~~~

  src/models/TimeSeries.ts:171:17
    171 export function TimeseriesFromJSON(json: any): Timeseries {
                        ~~~~~~~~~~~~~~~~~~
    'TimeseriesFromJSON' is declared here.

src/apis/LevelsApi.ts:34:5 - error TS2724: '"../models/index"' has no exported member named 'TimeSeriesToJSON'. Did you mean 'TimeseriesToJSON'?

34     TimeSeriesToJSON,
       ~~~~~~~~~~~~~~~~

  src/models/TimeSeries.ts:201:17
    201 export function TimeseriesToJSON(value?: Timeseries | null): any {
                        ~~~~~~~~~~~~~~~~
    'TimeseriesToJSON' is declared here.

src/apis/TimeSeriesApi.ts:20:3 - error TS2724: '"../models/index"' has no exported member named 'TimeSeries'. Did you mean 'Timeseries'?

20   TimeSeries,
     ~~~~~~~~~~

src/apis/TimeSeriesApi.ts:29:5 - error TS2724: '"../models/index"' has no exported member named 'TimeSeriesFromJSON'. Did you mean 'TimeseriesFromJSON'?

29     TimeSeriesFromJSON,
       ~~~~~~~~~~~~~~~~~~

  src/models/TimeSeries.ts:171:17
    171 export function TimeseriesFromJSON(json: any): Timeseries {
                        ~~~~~~~~~~~~~~~~~~
    'TimeseriesFromJSON' is declared here.

src/apis/TimeSeriesApi.ts:30:5 - error TS2724: '"../models/index"' has no exported member named 'TimeSeriesToJSON'. Did you mean 'TimeseriesToJSON'?

30     TimeSeriesToJSON,
       ~~~~~~~~~~~~~~~~

  src/models/TimeSeries.ts:201:17
    201 export function TimeseriesToJSON(value?: Timeseries | null): any {
                        ~~~~~~~~~~~~~~~~
    'TimeseriesToJSON' is declared here.

src/apis/TimeSeriesCategoriesApi.ts:19:3 - error TS2724: '"../models/index"' has no exported member named 'TimeSeriesCategory'. Did you mean 'TimeseriesCategory'?

19   TimeSeriesCategory,
     ~~~~~~~~~~~~~~~~~~

src/apis/TimeSeriesCategoriesApi.ts:24:5 - error TS2724: '"../models/index"' has no exported member named 'TimeSeriesCategoryFromJSON'. Did you mean 'TimeseriesCategoryFromJSON'?

24     TimeSeriesCategoryFromJSON,
       ~~~~~~~~~~~~~~~~~~~~~~~~~~

  src/models/TimeSeriesCategory.ts:50:17
    50 export function TimeseriesCategoryFromJSON(json: any): TimeseriesCategory {
                       ~~~~~~~~~~~~~~~~~~~~~~~~~~
    'TimeseriesCategoryFromJSON' is declared here.

src/apis/TimeSeriesCategoriesApi.ts:25:5 - error TS2724: '"../models/index"' has no exported member named 'TimeSeriesCategoryToJSON'. Did you mean 'TimeseriesCategoryToJSON'?

25     TimeSeriesCategoryToJSON,
       ~~~~~~~~~~~~~~~~~~~~~~~~

  src/models/TimeSeriesCategory.ts:66:17
    66 export function TimeseriesCategoryToJSON(value?: TimeseriesCategory | null): any {
                       ~~~~~~~~~~~~~~~~~~~~~~~~
    'TimeseriesCategoryToJSON' is declared here.

src/apis/TimeseriesGroupsApi.ts:19:3 - error TS2724: '"../models/index"' has no exported member named 'TimeSeriesGroup'. Did you mean 'TimeseriesGroup'?

19   TimeSeriesGroup,
     ~~~~~~~~~~~~~~~

src/apis/TimeseriesGroupsApi.ts:24:5 - error TS2724: '"../models/index"' has no exported member named 'TimeSeriesGroupFromJSON'. Did you mean 'TimeseriesGroupFromJSON'?

24     TimeSeriesGroupFromJSON,
       ~~~~~~~~~~~~~~~~~~~~~~~

  src/models/TimeSeriesGroup.ts:87:17
    87 export function TimeseriesGroupFromJSON(json: any): TimeseriesGroup {
                       ~~~~~~~~~~~~~~~~~~~~~~~
    'TimeseriesGroupFromJSON' is declared here.

src/apis/TimeseriesGroupsApi.ts:25:5 - error TS2724: '"../models/index"' has no exported member named 'TimeSeriesGroupToJSON'. Did you mean 'TimeseriesGroupToJSON'?

25     TimeSeriesGroupToJSON,
       ~~~~~~~~~~~~~~~~~~~~~

  src/models/TimeSeriesGroup.ts:107:17
    107 export function TimeseriesGroupToJSON(value?: TimeseriesGroup | null): any {
                        ~~~~~~~~~~~~~~~~~~~~~
    'TimeseriesGroupToJSON' is declared here.

src/models/ExpressionRating.ts:34:18 - error TS2310: Type 'ExpressionRating' recursively references itself as a base type.

34 export interface ExpressionRating extends AbstractRatingMetadata {
                    ~~~~~~~~~~~~~~~~

src/models/ExpressionRating.ts:34:43 - error TS2312: An interface can only extend an object type or intersection of object types with statically known members.

34 export interface ExpressionRating extends AbstractRatingMetadata {
                                             ~~~~~~~~~~~~~~~~~~~~~~

src/models/ExpressionRating.ts:69:41 - error TS2345: Argument of type 'ExpressionRating' is not assignable to parameter of type 'AbstractRatingMetadata'.
  Type 'ExpressionRating' is not assignable to type '{ ratingType: "expression-rating"; } & ExpressionRating'.
    Property 'ratingType' is missing in type 'ExpressionRating' but required in type '{ ratingType: "expression-rating"; }'.

69         ...AbstractRatingMetadataToJSON(value),
                                           ~~~~~

  src/models/AbstractRatingMetadata.ts:56:40
    56 export type AbstractRatingMetadata = { ratingType: 'expression-rating' } & ExpressionRating | { ratingType: 'table' } & TableRating | { ratingType: 'transitional' } & TransitionalRating | { ratingType: 'usgs' } & UsgsStreamRating | { ratingType: 'virtual' } & VirtualRating;
                                              ~~~~~~~~~~
    'ratingType' is declared here.

src/models/TableRating.ts:34:18 - error TS2310: Type 'TableRating' recursively references itself as a base type.        

34 export interface TableRating extends AbstractRatingMetadata {
                    ~~~~~~~~~~~

src/models/TableRating.ts:34:38 - error TS2312: An interface can only extend an object type or intersection of object types with statically known members.

34 export interface TableRating extends AbstractRatingMetadata {
                                        ~~~~~~~~~~~~~~~~~~~~~~

src/models/TableRating.ts:83:41 - error TS2345: Argument of type 'TableRating' is not assignable to parameter of type 'AbstractRatingMetadata'.
  Type 'TableRating' is not assignable to type '{ ratingType: "usgs"; } & UsgsStreamRating'.
    Property 'ratingType' is missing in type 'TableRating' but required in type '{ ratingType: "usgs"; }'.

83         ...AbstractRatingMetadataToJSON(value),
                                           ~~~~~

  src/models/AbstractRatingMetadata.ts:56:191
    56 export type AbstractRatingMetadata = { ratingType: 'expression-rating' } & ExpressionRating | { ratingType: 'table' } & TableRating | { ratingType: 'transitional' } & TransitionalRating | { ratingType: 'usgs' } & UsgsStreamRating | { ratingType: 'virtual' } & VirtualRating;
                                                                                                                        
                                                                             ~~~~~~~~~~
    'ratingType' is declared here.

src/models/TransitionalRating.ts:34:18 - error TS2310: Type 'TransitionalRating' recursively references itself as a base type.

34 export interface TransitionalRating extends AbstractRatingMetadata {
                    ~~~~~~~~~~~~~~~~~~

src/models/TransitionalRating.ts:34:45 - error TS2312: An interface can only extend an object type or intersection of object types with statically known members.

34 export interface TransitionalRating extends AbstractRatingMetadata {
                                               ~~~~~~~~~~~~~~~~~~~~~~

src/models/TransitionalRating.ts:83:41 - error TS2345: Argument of type 'TransitionalRating' is not assignable to parameter of type 'AbstractRatingMetadata'.
  Type 'TransitionalRating' is not assignable to type '{ ratingType: "transitional"; } & TransitionalRating'.
    Property 'ratingType' is missing in type 'TransitionalRating' but required in type '{ ratingType: "transitional"; }'.

83         ...AbstractRatingMetadataToJSON(value),
                                           ~~~~~

  src/models/AbstractRatingMetadata.ts:56:137
    56 export type AbstractRatingMetadata = { ratingType: 'expression-rating' } & ExpressionRating | { ratingType: 'table' } & TableRating | { ratingType: 'transitional' } & TransitionalRating | { ratingType: 'usgs' } & UsgsStreamRating | { ratingType: 'virtual' } & VirtualRating;
                                                                                                                        
                       ~~~~~~~~~~
    'ratingType' is declared here.

src/models/VirtualRating.ts:34:18 - error TS2310: Type 'VirtualRating' recursively references itself as a base type.    

34 export interface VirtualRating extends AbstractRatingMetadata {
                    ~~~~~~~~~~~~~

src/models/VirtualRating.ts:34:40 - error TS2312: An interface can only extend an object type or intersection of object types with statically known members.

34 export interface VirtualRating extends AbstractRatingMetadata {
                                          ~~~~~~~~~~~~~~~~~~~~~~

src/models/VirtualRating.ts:76:41 - error TS2345: Argument of type 'VirtualRating' is not assignable to parameter of type 'AbstractRatingMetadata'.
  Type 'VirtualRating' is not assignable to type '{ ratingType: "virtual"; } & VirtualRating'.
    Property 'ratingType' is missing in type 'VirtualRating' but required in type '{ ratingType: "virtual"; }'.

76         ...AbstractRatingMetadataToJSON(value),
                                           ~~~~~

  src/models/AbstractRatingMetadata.ts:56:235
    56 export type AbstractRatingMetadata = { ratingType: 'expression-rating' } & ExpressionRating | { ratingType: 'table' } & TableRating | { ratingType: 'transitional' } & TransitionalRating | { ratingType: 'usgs' } & UsgsStreamRating | { ratingType: 'virtual' } & VirtualRating;
                                                                                                                        
                                                                                                                        
 ~~~~~~~~~~
    'ratingType' is declared here.

npm run openapi-test

[adamkorynta]

Related: #495

[MikeNeilson]

Followup: Charles and I were finally able to look at this directly and the Swagger output is "incorrect." At the very least it's definitely inconsistent in several places.

In no particular order:

• For the TimeSeries object itself, it's not camel cased because there is an anotation for XML that forces lower case, we tested adding @Schema("TimeSeries") to the TimeSeries class and that did correct the swagger output
• For the camel casing in method names. the operatorId is generating the names based on the path and, split by /, the first character of each path element is capitalized but we just use "timeseries". Javalin is case sensitive to URLs but there is a plugin to add case-insetivity, we need to check that this doesn't apply to the path parameters -- pretty sure it doesn't and if not we can camel case all the names appropriately without affecting other usage.
• we could also manually remove CwmsData from the operatorId but the next bullet may be the better solution.
• For the base path, this is a side affect of original issues getting swagger to work; however, I think that challenge may be overcome(able)-by-events. Since we are already tweaking the OpenAPI spec on-the-fly (for the security settings) we can determine and use the context; additional we can generate the swagger-ui yaml config on the fly too (honestly not sure why I didn't think of that before. This will allow using the basePath correctly and clean up the names that would be used by the automatic generators.

I think we've determine the TimeSeries.Record being an "object" but TimeSeries' list of TimeSeries.Record being an array, isn't really solvable at the moment. In the component spec of the OpenAPI TimeSeries.Record is, correctly, an object but it's usage in TimeSeries' list is to render as a list.

However, given the recent change for data_entry_date and a future change for text notes, I'm thinking that Record my go away in favor of an actual, in the java parlance, List<List>, since we've clearly established that the value-columns defines the columns and downstream systems should respect that.
But it may still be good to leave it as an object in the openapi spec so we can insert the possible descriptions. We'll have to see when the time comes.

I will eventually open issues for all that work. We will leave this one open to and link those to this issue.

I want to thank @krowvin for not letting the issue go so that it will get resolved.
Not an excused but my assumption was that because no other downstream library reported issues that it was likely with the generator; however, @krowvin and I realized during the discussion that the java client only uses a generator for the data types and the python client doesn't use a generator at all, so especially the operatorId portion was not apparent. And when I validated things I mostly just looked at swagger and verified the contexts were correct; I should've been a bit more picky about the DTO names and how they were rendered.

For the record, except for things we can only really determine at runtime, like the "servers" and certain security schemes, we do consider issues with the OpenAPI spec to be a bug. It's generation should be at a minimum sensible, if not perfectly useable by every client generator.