Tcm 5257 summarize issues with swagger api documentation for creating sdk#246
Conversation
DmitryMasley
requested review from
DmitryBochorishvili,
Jackalx,
dimitrystd,
junky,
klegins-smartling and
msogin
| application/json: | ||
| schema: | ||
| $ref: '#/components/schemas/Error400Response' | ||
| $ref: '../api_common.yaml#/components/schemas/Error400Response' |
There was a problem hiding this comment.
I assume api_common.yaml is a most common description of the response
| defaultLocaleId: | ||
| type: string | ||
| description: Smartling's default locale that corresponds to languageId | ||
| properties: |
There was a problem hiding this comment.
object should have properties attribute
| tags: | ||
| - File Machine Translations (MT) | ||
| operationId: mtFile | ||
| consumes: |
There was a problem hiding this comment.
consumes and produces no longer exist in openapi v3
There was a problem hiding this comment.
consumes was replaced by requestBody and produces described in responses
| GetGlossaryEntriesByFilterCommandPTO: | ||
| type: object | ||
| required: | ||
| - entryState |
There was a problem hiding this comment.
required fields of the object described in the separate array field required
| url: 'https://help.smartling.com' | ||
|
|
||
| security: | ||
| - BearerAuth: [] |
There was a problem hiding this comment.
I assume all the API is using BearerAuth. Please, correct it if it is wrong.
| # Issues API endpoints | ||
| # | ||
| /issues-api/v2/dictionary/issue-states: | ||
| $ref: './spec/issues/dictionaries.yaml#/x-paths/dictionary_issues_states' |
There was a problem hiding this comment.
reference relative to the file, rather than the root of the project.
| description: The text to translate | ||
| example: Text to translate | ||
| type: string | ||
| maxLength: 64kb |
There was a problem hiding this comment.
maxLength can only be number
| description: >- | ||
| Whether translator instructions have been captured for the | ||
| file | ||
| type: integer |
There was a problem hiding this comment.
description indicates it is boolean
|
|
|
Very common lint error: schema does not match examples. In many cases, the schema is defined incorrectly. Sometimes arrays are defined where there has to be an object, sometimes, an object is defined in place of an array. |
|
@AlexArcher idk what Edit: |
Tqct 1058 fix issues and TQC warnings
…-documentation-for-creating-sdk
6 participants
testscript to validate and lint the documentationnpm run testscript will show linting errors.npm run test -- --format=stylishwill produce a more compact output grouped by filePreview link