Wrote OpenAPI Spec for Self-Defined #72
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,390 @@ | ||||||
| openapi: 3.0.1 | ||||||
| info: | ||||||
| title: Self Defined | ||||||
| description: | | ||||||
| A modern dictionary about us. We define our words, but they don't define us. [Self-Defined](https://www.selfdefined.app/) seeks to provide more inclusive, holistic, and fluid definitions to reflect the modern world. The goal for [Self-Defined](https://www.selfdefined.app/) is to become the first modern dictionary that reflects our digital world, using the best aspects of technology while minimising the worst aspects of technology that can cause harm. [Self-Defined](https://www.selfdefined.app/) is successful if it supports greater, more nuanced understanding and tolerance of fellow humans through words. | ||||||
| termsOfService: https://www.selfdefined.app/terms-of-service | ||||||
| # contact: | ||||||
| # email: apiteam@swagger.io | ||||||
| # license: | ||||||
| # name: Apache 2.0 | ||||||
| # url: http://www.apache.org/licenses/LICENSE-2.0.html | ||||||
| version: 1.0.0 | ||||||
| externalDocs: | ||||||
| description: Find out more | ||||||
| url: https://github.com/tatianamac/selfdefined | ||||||
| servers: | ||||||
| - url: https://api.selfdefined.app/ | ||||||
| tags: | ||||||
| - name: Word | ||||||
| description: Self-Defined Words | ||||||
| externalDocs: | ||||||
| description: Find out more | ||||||
| url: https://schemas.selfdefined.app/words | ||||||
| components: | ||||||
| schemas: | ||||||
| Word: | ||||||
| allOf: | ||||||
| - $ref: '#/components/schemas/Id' | ||||||
| - $ref: '#/components/schemas/NewWord' | ||||||
| FullWord: | ||||||
| allOf: | ||||||
| - $ref: '#/components/schemas/Word' | ||||||
| - $ref: '#/components/schemas/Translations' | ||||||
| - $ref: '#/components/schemas/Synonyms' | ||||||
| - $ref: '#/components/schemas/Alternatives' | ||||||
| - $ref: '#/components/schemas/FurtherReadings' | ||||||
| ShortLink: | ||||||
| description: Shortlink terms which map to this word. | ||||||
| type: object | ||||||
| properties: | ||||||
| shortLinkText: | ||||||
| type: string | ||||||
| word: | ||||||
| $ref: '#/components/schemas/Link' | ||||||
| required: | ||||||
| - shortLink | ||||||
| - word | ||||||
| Link: | ||||||
| type: object | ||||||
| properties: | ||||||
| displayName: | ||||||
| type: string | ||||||
| url: | ||||||
| type: string | ||||||
| format: url | ||||||
| icon: | ||||||
| type: string | ||||||
| format: url | ||||||
| required: | ||||||
| - displayName | ||||||
| - url | ||||||
| Translations: | ||||||
| type: object | ||||||
| properties: | ||||||
| translations: | ||||||
| type: array | ||||||
| minItems: 0 | ||||||
| items: | ||||||
| $ref: '#/components/schemas/Link' | ||||||
|
There was a problem hiding this comment. Should the Translations, Synonyms, and Alternatives be Word types instead of Link types? We can have them in their own containers rather than embedded in the Word object themselves.
Suggested change
|
||||||
| Synonyms: | ||||||
| type: object | ||||||
| properties: | ||||||
| synonyms: | ||||||
| type: array | ||||||
| minItems: 0 | ||||||
| items: | ||||||
| $ref: '#/components/schemas/Link' | ||||||
|
There was a problem hiding this comment.
Suggested change
|
||||||
| Alternatives: | ||||||
| description: A positive alternative choice to communicate without exclusion. | ||||||
| type: object | ||||||
| properties: | ||||||
| alternatives: | ||||||
| type: array | ||||||
| minItems: 0 | ||||||
| items: | ||||||
| $ref: '#/components/schemas/Link' | ||||||
|
Comment on lines
+62
to
+86
There was a problem hiding this comment. Should the Translations, Synonyms, and Alternatives be Word types instead of Link types? We can have them in their own containers rather than embedded in the Word object themselves. There was a problem hiding this comment.
Suggested change
|
||||||
| FurtherReadings: | ||||||
| description: For further reading on the word. | ||||||
| type: object | ||||||
| properties: | ||||||
| furtherReadings: | ||||||
| type: array | ||||||
| minItems: 0 | ||||||
| items: | ||||||
| $ref: '#/components/schemas/Link' | ||||||
| NewWord: | ||||||
| type: object | ||||||
| properties: | ||||||
| displayName: | ||||||
| type: string | ||||||
| definition: | ||||||
| type: string | ||||||
| originLanguage: | ||||||
| type: string | ||||||
| description: This should be the ISO internationalization value. | ||||||
| tag: | ||||||
|
There was a problem hiding this comment. Tag should be an array because multiple tags might apply. I like the enum but it might be better to allow it to be dynamic and let the API implementation and/or web front end enforce rules around how they're created/added to the word. |
||||||
| type: object | ||||||
| properties: | ||||||
| displayName: | ||||||
| type: string | ||||||
| enum: &word-tags | ||||||
| - ABLEIST SLUR | ||||||
| - RACIST SYMBOL | ||||||
| - CULTURAL APPROPRIATION | ||||||
| - ANTI-TRANS SLUR | ||||||
| - NEO-COLONIAL RACIST SLUR | ||||||
| - MEDICAL APPROPRIATION | ||||||
| - TOOL OF OPPRESSION | ||||||
| icon: | ||||||
| type: string | ||||||
| format: url | ||||||
| required: | ||||||
| - displayName | ||||||
| wordStatus: | ||||||
| type: string | ||||||
| enum: | ||||||
| - AVOID | ||||||
| - PREFERRED | ||||||
| - ACCEPTABLE | ||||||
| wordType: | ||||||
| type: string | ||||||
| enum: &word-types | ||||||
| - ADJECTIVE | ||||||
| - NOUN | ||||||
| - VERB | ||||||
| - ADVERB | ||||||
| issues: | ||||||
| type: string | ||||||
| impact: | ||||||
| type: string | ||||||
| notes: | ||||||
| type: string | ||||||
| usageTips: | ||||||
| type: string | ||||||
| required: | ||||||
| - displayName | ||||||
| - definition | ||||||
| - wordStatus | ||||||
| - wordType | ||||||
| NewTranslation: | ||||||
| $ref: '#/components/schemas/Link' | ||||||
| NewSynonym: | ||||||
| $ref: '#/components/schemas/Link' | ||||||
| NewAlternative: | ||||||
| $ref: '#/components/schemas/Link' | ||||||
| NewFurtherReading: | ||||||
| $ref: '#/components/schemas/Link' | ||||||
| NewShortLink: | ||||||
| description: Shortlink terms which map to this word. | ||||||
| type: object | ||||||
| properties: | ||||||
| shortLinkText: | ||||||
| type: string | ||||||
| wordLink: | ||||||
| type: string | ||||||
| format: url | ||||||
| required: | ||||||
| - shortLink | ||||||
| - word | ||||||
| Id: | ||||||
| type: object | ||||||
| properties: | ||||||
| id: | ||||||
| type: string | ||||||
| format: uuid | ||||||
| required: | ||||||
| - id | ||||||
| # Commenting all this out for now to just get things up and running. | ||||||
| # securitySchemes: | ||||||
| # petstore_auth: | ||||||
| # type: oauth2 | ||||||
| # flows: | ||||||
| # implicit: | ||||||
| # authorizationUrl: http://petstore.swagger.io/oauth/dialog | ||||||
| # scopes: | ||||||
| # write:pets: modify pets in your account | ||||||
| # read:pets: read your pets | ||||||
| # api_key: | ||||||
| # type: apiKey | ||||||
| # name: api_key | ||||||
| # in: header | ||||||
|
|
||||||
| paths: | ||||||
| '/words': | ||||||
| get: | ||||||
| tags: | ||||||
| - Word | ||||||
| summary: Find Words | ||||||
| operationId: findWords | ||||||
| responses: &words-responses | ||||||
| 200: | ||||||
| description: Successful Request | ||||||
| content: | ||||||
| application/vnd.self-defined.words+json: | ||||||
| schema: | ||||||
| type: array | ||||||
| items: | ||||||
| $ref: '#/components/schemas/Word' | ||||||
| application/vnd.self-defined.full-words+json: | ||||||
| schema: | ||||||
| type: array | ||||||
| items: | ||||||
| $ref: '#/components/schemas/FullWord' | ||||||
| 404: | ||||||
| description: Not Found | ||||||
| post: | ||||||
| tags: | ||||||
| - Word | ||||||
| summary: Add Word | ||||||
| operationId: addWord | ||||||
| requestBody: | ||||||
| description: Add word to dictionary | ||||||
| content: | ||||||
| application/vnd.self-defined.new-word+json: | ||||||
| schema: | ||||||
| $ref: '#/components/schemas/NewWord' | ||||||
| responses: | ||||||
| 200: | ||||||
| description: Successful Request | ||||||
| content: | ||||||
| application/vnd.self-defined.word+json: | ||||||
| schema: | ||||||
| $ref: '#/components/schemas/Word' | ||||||
| 400: | ||||||
| description: Bad Request | ||||||
| '/words/{wordId}': | ||||||
| parameters: | ||||||
| - name: wordId | ||||||
| in: path | ||||||
| description: ID of word to return | ||||||
| required: true | ||||||
| schema: | ||||||
| type: string | ||||||
| format: uuid | ||||||
| get: | ||||||
| tags: | ||||||
| - Word | ||||||
| summary: Get Words | ||||||
| operationId: getWord | ||||||
| responses: &word-responses | ||||||
| 200: | ||||||
| description: Successful Request | ||||||
| content: | ||||||
| application/vnd.self-defined.word+json: | ||||||
| schema: | ||||||
| $ref: '#/components/schemas/Word' | ||||||
| application/vnd.self-defined.translations+json: | ||||||
| schema: | ||||||
| allOf: | ||||||
| - $ref: '#/components/schemas/Id' | ||||||
| - $ref: '#/components/schemas/Translations' | ||||||
| application/vnd.self-defined.synonyms+json: | ||||||
| schema: | ||||||
| allOf: | ||||||
| - $ref: '#/components/schemas/Id' | ||||||
| - $ref: '#/components/schemas/Synonyms' | ||||||
| application/vnd.self-defined.alternatives+json: | ||||||
| schema: | ||||||
| allOf: | ||||||
| - $ref: '#/components/schemas/Id' | ||||||
| - $ref: '#/components/schemas/Alternatives' | ||||||
| application/vnd.self-defined.further-readings+json: | ||||||
| schema: | ||||||
| allOf: | ||||||
| - $ref: '#/components/schemas/Id' | ||||||
| - $ref: '#/components/schemas/FurtherReadings' | ||||||
| application/vnd.self-defined.full-word+json: | ||||||
| schema: | ||||||
| $ref: '#/components/schemas/FullWord' | ||||||
| 404: | ||||||
| description: Not Found | ||||||
| put: | ||||||
| tags: | ||||||
| - Word | ||||||
| description: Update related words links | ||||||
| summary: Update related words links | ||||||
| operationId: updateRelatedWords | ||||||
| requestBody: | ||||||
| description: Relationship link to add to this word | ||||||
| content: | ||||||
| application/vnd.self-defined.translations+json: | ||||||
| schema: | ||||||
| $ref: '#/components/schemas/Translations' | ||||||
| application/vnd.self-defined.synonyms+json: | ||||||
| schema: | ||||||
| $ref: '#/components/schemas/Synonyms' | ||||||
| application/vnd.self-defined.alternatives+json: | ||||||
| schema: | ||||||
| $ref: '#/components/schemas/Alternatives' | ||||||
| application/vnd.self-defined.further-readings+json: | ||||||
| schema: | ||||||
| $ref: '#/components/schemas/FurtherReadings' | ||||||
| responses: *word-responses | ||||||
| post: | ||||||
| tags: | ||||||
| - Word | ||||||
| description: Add related words links | ||||||
| summary: Add related words links | ||||||
| operationId: addRelatedWords | ||||||
| requestBody: | ||||||
| description: Relationship link to add to this word | ||||||
| content: | ||||||
| application/vnd.self-defined.new-translation+json: | ||||||
| schema: | ||||||
| $ref: '#/components/schemas/NewTranslation' | ||||||
| application/vnd.self-defined.new-synonym+json: | ||||||
| schema: | ||||||
| $ref: '#/components/schemas/NewSynonym' | ||||||
| application/vnd.self-defined.new-alternative+json: | ||||||
| schema: | ||||||
| $ref: '#/components/schemas/NewAlternative' | ||||||
| application/vnd.self-defined.new-further-reading+json: | ||||||
| schema: | ||||||
| $ref: '#/components/schemas/NewFurtherReading' | ||||||
| responses: *word-responses | ||||||
| delete: | ||||||
| tags: | ||||||
| - Word | ||||||
| summary: Remove Word | ||||||
| operationId: deleteWord | ||||||
| responses: | ||||||
| 204: | ||||||
| description: No Content | ||||||
| 404: | ||||||
| description: Not Found | ||||||
| '/shortlinks': | ||||||
| post: | ||||||
| tags: | ||||||
| - Shortlink | ||||||
| summary: Add Shortlink | ||||||
| operationId: addShortlink | ||||||
| requestBody: | ||||||
| description: Add Shortlink to a word | ||||||
| content: | ||||||
| application/vnd.self-defined.new-short-link+json: | ||||||
| schema: | ||||||
| $ref: '#/components/schemas/NewShortLink' | ||||||
| responses: &shortlink-responses | ||||||
| 200: | ||||||
| description: Successful Request | ||||||
| content: | ||||||
| application/vnd.self-defined.short-link+json: | ||||||
| schema: | ||||||
| $ref: '#/components/schemas/ShortLink' | ||||||
| application/vnd.self-defined.short-link-word+json: | ||||||
| schema: | ||||||
| allOf: | ||||||
| - $ref: '#/components/schemas/ShortLink' | ||||||
| - $ref: '#/components/schemas/Word' | ||||||
| application/vnd.self-defined.short-link-full-word+json: | ||||||
| schema: | ||||||
| allOf: | ||||||
| - $ref: '#/components/schemas/ShortLink' | ||||||
| - $ref: '#/components/schemas/FullWord' | ||||||
| 404: | ||||||
| description: Not Found | ||||||
| '/shortlinks/{shortLinkId}': | ||||||
| parameters: | ||||||
| - name: shortLinkId | ||||||
| in: path | ||||||
| description: Percent encoded value of shortlink value for profile linking | ||||||
| required: true | ||||||
| schema: | ||||||
| type: string | ||||||
| get: | ||||||
| tags: | ||||||
| - Shortlink | ||||||
| summary: Get Shortlink | ||||||
| operationId: getShortlink | ||||||
| responses: *shortlink-responses | ||||||
| delete: | ||||||
| tags: | ||||||
| - Shortlink | ||||||
| summary: Remove Shortlink | ||||||
| operationId: deleteShortlink | ||||||
| responses: | ||||||
| 204: | ||||||
| description: No Content | ||||||
| 404: | ||||||
| description: Not Found | ||||||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Should this be shortLinkText to match the property