Skip to content
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.

Sign up for GitHub

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

Jump to bottom

Document one REST endpoint with springdoc #82 #150

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Document one REST endpoint with springdoc #82 #150

wants to merge 4 commits into from

Conversation

palagdan
Copy link
Collaborator

Resolves #82
if you like this style of documentation, I can document the other endpoints in the current ticket.

@palagdan palagdan requested a review from blcham August 22, 2024 10:55
@palagdan
Copy link
Collaborator Author

palagdan commented Sep 11, 2024 •
edited
Loading

@blcham

I'm currently blocked by this ticket. I've spent a lot of time trying to figure out why I can't access the generated Springdoc when using internal authorization via an Nginx deployment.

When I make a direct request to the backend running locally, I receive the correct API documentation. As you can see from the screenshots, the URLs are identical, and Nginx should be proxying the same path.

Nginx deployment (Springdoc not generated):

Screenshot from 2024-09-11 08-39-08

Local backend (API doc available):
Screenshot from 2024-09-11 08-53-53

Also I am not sure about this annotation:

@Operation(security = {@SecurityRequirement(name = "bearer-key")

If we are using internal authorization, accessing the Springdoc should only require a session ID to pass the security filter. Bearer tokens are only necessary when OAuth is in use.

@kostobog kostobog mentioned this pull request Sep 12, 2024
Merged
blcham
blcham requested changes Sep 12, 2024
View reviewed changes
Copy link
Contributor

@blcham blcham left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@kostobog see my comments

src/main/java/cz/cvut/kbss/analysis/controller/ComponentController.java Outdated
@ApiResponses(value = {
@ApiResponse(responseCode = "201", description = "Failure mode added"),
@ApiResponse(responseCode = "400", description = """
Invalid Invalid failureMode, e.g.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Invalid Invalid failureMode, e.g.
Invalid failure mode, e.g.

src/main/java/cz/cvut/kbss/analysis/controller/ComponentController.java Outdated
Comment on lines 113 to 115
- The uri should be null or unique
- Duplicate entity name
- Name must not be empty
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- The uri should be null or unique
- Duplicate entity name
- Name must not be empty
- failure mode uri is not null nor unique.
- failure mode name already exists.
- failure mode name is empty.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I tried to make it more consistent as it seemed to me that some of the bulets have semantics of errors (Duplicate entity name) and other ones semantics of constraints (The uri should be null or unique)

Copy link
Collaborator

@kostobog kostobog Sep 12, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@blcham
Ok but there are two issues:

  • I will have to update the actual messages in the exceptions/validation-errors.
  • these messages are generic - I will have to find a way to add the entity type, e.g. failure mode) to the message.

See commit d954733

@palagdan palagdan requested a review from blcham October 14, 2024 11:26
@palagdan
Copy link
Collaborator Author

@blcham
swagger
I described in the README.md how to access Swagger. It works when you make requests directly to the backend only for authorized users.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@kostobog kostobog kostobog left review comments

@blcham blcham Awaiting requested review from blcham

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

Document one REST endpoint with springdoc
3 participants
@palagdan @blcham @kostobog