-
Notifications
You must be signed in to change notification settings - Fork 22
feat(ls): add documentation rules for OpenAPI 3.1.0 #1946
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Conversation
Initial definition (modified fixture): openapi: 3.1.0
info:
title: deref
version: 1.0.0
servers:
- description: local
url: http://localhost:8082/
paths:
/a:
get:
operationId: aget
parameters:
- $ref: '#/components/parameters/userId'
servers:
- description: extendedm
url: http://localhost:8080
parameters:
- name: id
in: path
description: ID of pet to use
required: true
schema:
type: array
items:
type: string
style: simple
post:
operationId: apost
/b:
get:
operationId: bget
parameters:
- $ref: '#/components/parameters/userId'
post:
operationId: bpost
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/foo'
components:
schemas:
foo:
type: string
bar:
$id: http://localhost:8082/
type: string
parameters:
userId:
$ref: '#/components/parameters/indirection1'
description: override
indirection1:
$ref: '#/components/parameters/indirection2'
summary: indirect summary
indirection2:
$ref: '#/components/parameters/userIdRef'
summary: indirect summary
userIdRef:
name: userId
in: query
description: ID of the user
required: true
externalRef:
$ref: ./ex.json#/externalParameter
description: another ref |
Notes:
|
packages/apidom-ls/src/config/openapi/path-item/documentation.ts
Outdated
Show resolved
Hide resolved
packages/apidom-ls/src/config/openapi/path-item/documentation.ts
Outdated
Show resolved
Hide resolved
packages/apidom-ls/src/config/openapi/path-item/documentation.ts
Outdated
Show resolved
Hide resolved
@frantuma working on If this snippet here is uncommented, then I can verify in apidom-playground, that the element is found and described as I tried different naming conventions in Here's the minimal spec used for apidom-playground: openapi: 3.1.0
info:
title: deref
version: 1.0.0
servers:
- description: local
url: http://localhost:8082/
variables:
username:
# note! no enum here means it is an open value
default: demo
description: this value is assigned by the service provider, in this example `gigantic-server.com`
port:
enum:
- '8443'
- '443'
default: '8443'
basePath:
# open meaning there is the opportunity to use special base paths as assigned by the provider, default is `v2`
default: v2 Also the syntax highlight doesn't apply in this screenshot: Seems like there's a difference between |
This is correct, as
Not sure here what you mean? display the docs? or? see above
I don't think this is correct: The "classifier" defined for the server-variables element is server-variables. I have seen you added to File In order to have some visible highlight, obviously it must be configured on the editor side as well |
@tim-lai 2 additional not so related comments:
|
It's not picking up docs from I also tried adding the following to
|
Resolved. Also removed the above mentioned At this moment, only remaining issue is rendering docs from |
Still not clear to me if we are referring to singular ( A couple of points to recap/clarify:
Notice also that you are mixing plural/singular as in current code relates variables to variable (singular) meta. You should instead add a meta directory for Alternatively, and possibly easier in this case, uncommenting the docs in server for target
|
This did the trick! This is my preferred solution, to import the meta docs. PR updated in 393ca65. For clarity:
Ok, good to know. Let me know if/when changes are needed. Also, where would I have been able to see these naming classifiers? |
@tim-lai not sure if we are there yet IIANM, your current code would cause the rendering of this doc when hovering the key
As mentioned in comment above: Notice also that you are mixing plural/singular as in current code relates variables to variable (singular) meta. You should instead add a meta directory for server-variables and set docs there, and import/use that one in config. |
about "classifiers", these are either element field or member of classes of an apidom ns element, see also here. In local code, the most handy way atm is to search in root path for |
That was my intent, because If we go back and revisit That said, upon further review, So would this be an acceptable standard?
fwiw, the Operation Object meta documentation follows this standard, but that's because I haven't gotten to building out the available meta fields for it. :) Another question, with the above standard, how would a user would visualize a meta data object like Separately, I'll change the meta directory name to |
I am having difficulties understanding your point(s):
A Variable has its own doc, which should be rendered in hover when hovering over the variable key. This is exactly the same as the logic applied to asyncapi, which got its variables and stuff from openapi. Please try hovering the following doc loaded in editor next:
see above,
I am not sure I understand what you mean, please check how done in asyncapi with parameters and references
Not sure I understand, puzzled by "multiple type", "table description". I would again point to asyncapi behavior, the "standard" is to use the docs provided by the spec relative to the field. So in your example
Not sure I get this, please look at AsyncAPI operation, this is the same. In your current code it looks ok I guess, with fields docs (with
Assuming "visualize" means rendering the docs on hover, this is covered by previous points, see asyncapi:
tag: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#tagObject $ref: see async, e.g. for parameter |
Alrighty, I think I am understanding better now. Cumulative updates for review in ef487ad. Based on all the comments and changes, I'm thinking this line can safely be removed (along with the import and the referenced directory)?
|
current fixture, up to e9d8130.
openapi: 3.1.0
info:
title: deref
version: 1.0.0
license:
name: Apache 2.0
identifier: Apache-2.0
contact:
name: API Support
url: https://www.example.com/support
email: support@example.com
servers:
- description: local
url: http://localhost:8082/
variables:
username:
# note! no enum here means it is an open value
default: demo
description: this value is assigned by the service provider, in this example `gigantic-server.com`
port:
enum:
- '8443'
- '443'
default: '8443'
basePath:
# open meaning there is the opportunity to use special base paths as assigned by the provider, default is `v2`
default: v2
tags:
- name: first tag
description: basic first tag
- name: second tag with external
description: tag description with externalDoc
externalDocs:
description: Find out more
url: http://swagger.io
externalDocs:
description: externalDocs for main schema
url: http://localhost:8080
webhooks:
security:
jsonSchemaDialect:
paths:
/a:
get:
operationId: aget
tags:
- name: apple
description: operation apple
- name: banana
description: operation banana
summary: short explanation
description: longer explanation
deprecated: false
parameters:
- $ref: '#/components/parameters/userId'
externalDocs:
description: externalDocs for operation /get a
url: http://localhost:8080
servers:
- description: extendedm
url: http://localhost:8080
- description: secondServ
url: http://localhost:8081
variables:
color:
default: blue
responses:
'200':
description: a pet to be returned
content:
application/json:
schema:
$ref: '#/components/schemas/Pet'
headers:
description: The number of allowed requests in the current period
schema:
type: integer
links:
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
post:
operationId: apost
parameters:
- name: id
in: path
description: ID of pet to use
required: true
schema:
type: array
items:
type: string
style: simple
examples:
example:
/b:
get:
operationId: bget
parameters:
- $ref: '#/components/parameters/userId'
post:
operationId: bpost
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/foo' |
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.
@tim-lai thanks for starting the work on this. I've finished my deep code review and suggested many changes and enhancements. The goal now should be to stabilize code in this PR, not produce any new stuff and get this PR into state that is mergable, so that rules for OpenAPI 3.0.x production can start in parallel.
Then it would be good if process of producing further documentation for OpenAPI 3.1.0 changes and instead of producing huge PRs, small PRs containing documentation for one/two specification objects would be more appropriate. It would make code reviews more effective and quicker.
packages/apidom-ls/src/config/openapi/external-documentation/documentation.ts
Show resolved
Hide resolved
packages/apidom-ls/src/config/openapi/external-documentation/meta.ts
Outdated
Show resolved
Hide resolved
packages/apidom-ls/src/config/openapi/parameter/documentation.ts
Outdated
Show resolved
Hide resolved
packages/apidom-ls/src/config/openapi/parameter/documentation.ts
Outdated
Show resolved
Hide resolved
packages/apidom-ls/src/config/openapi/parameter/documentation.ts
Outdated
Show resolved
Hide resolved
Also initial documentation for * server * server-variables
9f29206
to
ae23041
Compare
@char0n Thanks for the detailed review! I've either resolved or commented on all requested changes, please take another look. Summary:
2 additional questions:
|
Thanks for changes. Doing second round of CR now.
Nothing to worry about. Only linting of commit messages failed. This PR is going to be squash-merged anyway and new commit msg will be provided.
Let's deal with this separately after this PR. We can schedule a session where we can talk about rules of configs production. |
packages/apidom-ls/src/config/openapi/openapi3_1/documentation.ts
Outdated
Show resolved
Hide resolved
packages/apidom-ls/src/config/openapi/openapi3_1/documentation.ts
Outdated
Show resolved
Hide resolved
@tim-lai I've reacted there, have a look at it please. After we address rest of this comments, we should be able to go for merge during today/tommorow. |
Requested changes should now all be resolved. Please have one more look. Thanks! |
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.
LGTM, nicely done.
Let me just reiterate what I wrote before: It would be good if process of producing further documentation for OpenAPI 3.1.0 changes, and instead of producing huge PRs, small PRs containing documentation for one/two specification objects would be more appropriate. It would make code reviews more effective and quicker.
Last thing: I recommend squash+merging this PR into one if possible with following commit msg:
feat(ls): add documentation rules for OpenAPI 3.1.0
Ref <issue number>
Ref: #1975, #1976, #1977, #1978, #1979, #1980, #1981, #1982, #1983, #1984, #1985
Description
Render documentation in Monaco for the following elements:
externalDocumentation
license
openapi3_1
operation
paths
pathItem
parameter
responses
server
serverVariable
tag
refer to comments for additional progressive setup/screenshots/notes.
Motivation and Context
Build out
apidom-ls
rules for OAS3.1Ref: #1975
Ref: #1976
Ref: #1977
Ref: #1978
Ref: #1979
Ref: #1980
Ref: #1981
Ref: #1982
Ref: #1983
Ref: #1984
Ref: #1985
How Has This Been Tested?
local. No new tests yet.
Screenshots (if appropriate):
Checklist
My PR contains...
src/
is unmodified: changes to documentation, CI, metadata, etc.)package.json
)My changes...
Documentation
Automated tests