docs: add swagger annotations for check with mirrored status codes

README.md

@@ -96,21 +96,17 @@ An overview of what is implemented and upcoming can be found at
 
 <!--BEGIN ADOPTERS-->
 
-The Ory community stands on the shoulders of individuals, companies, and
-maintainers. We thank everyone involved - from submitting bug reports and
-feature requests, to contributing patches, to sponsoring our work. Our community
-is 1000+ strong and growing rapidly. The Ory stack protects 16.000.000.000+ API
-requests every month with over 250.000+ active service nodes. We would have
+The Ory community stands on the shoulders of individuals, companies, and maintainers. We thank everyone involved - from submitting
+bug reports and feature requests, to contributing patches, to sponsoring our work. Our community is 1000+ strong and growing
+rapidly. The Ory stack protects 16.000.000.000+ API requests every month with over 250.000+ active service nodes. We would have
 never been able to achieve this without each and everyone of you!
 
-The following list represents companies that have accompanied us along the way
-and that have made outstanding contributions to our ecosystem. _If you think
-that your company deserves a spot here, reach out to
+The following list represents companies that have accompanied us along the way and that have made outstanding contributions to our
+ecosystem. _If you think that your company deserves a spot here, reach out to
 <a href="mailto:[email protected]">[email protected]</a> now_!
 
-**Please consider giving back by becoming a sponsor of our open source work on
-<a href="https://www.patreon.com/_ory">Patreon</a> or
-<a href="https://opencollective.com/ory">Open Collective</a>.**
+**Please consider giving back by becoming a sponsor of our open source work on <a href="https://www.patreon.com/_ory">Patreon</a>
+or <a href="https://opencollective.com/ory">Open Collective</a>.**
 
 <table>
     <thead>
@@ -277,10 +273,8 @@ as well as all of our backers
 
 <a href="https://opencollective.com/ory#backers" target="_blank"><img src="https://opencollective.com/ory/backers.svg?width=890"></a>
 
-and past & current supporters (in alphabetical order) on
-[Patreon](https://www.patreon.com/_ory): Alexander Alimovs, Billy, Chancy
-Kennedy, Drozzy, Edwin Trejos, Howard Edidin, Ken Adler Oz Haven, Stefan Hans,
-TheCrealm.
+and past & current supporters (in alphabetical order) on [Patreon](https://www.patreon.com/_ory): Alexander Alimovs, Billy, Chancy
+Kennedy, Drozzy, Edwin Trejos, Howard Edidin, Ken Adler Oz Haven, Stefan Hans, TheCrealm.
 
 <em>\* Uses one of Ory's major projects in production.</em>
 
@@ -294,51 +288,42 @@ Head over to the documentation to learn about ways of [installing ORY Keto](http
 
 <!--BEGIN ECOSYSTEM-->
 
-We build Ory on several guiding principles when it comes to our architecture
-design:
+We build Ory on several guiding principles when it comes to our architecture design:
 
 - Minimal dependencies
 - Runs everywhere
 - Scales without effort
 - Minimize room for human and network errors
 
-Ory's architecture is designed to run best on a Container Orchestration system
-such as Kubernetes, CloudFoundry, OpenShift, and similar projects. Binaries are
-small (5-15MB) and available for all popular processor types (ARM, AMD64, i386)
-and operating systems (FreeBSD, Linux, macOS, Windows) without system
-dependencies (Java, Node, Ruby, libxml, ...).
+Ory's architecture is designed to run best on a Container Orchestration system such as Kubernetes, CloudFoundry, OpenShift, and
+similar projects. Binaries are small (5-15MB) and available for all popular processor types (ARM, AMD64, i386) and operating
+systems (FreeBSD, Linux, macOS, Windows) without system dependencies (Java, Node, Ruby, libxml, ...).
 
 ### Ory Kratos: Identity and User Infrastructure and Management
 
-[Ory Kratos](https://github.com/ory/kratos) is an API-first Identity and User
-Management system that is built according to
-[cloud architecture best practices](https://www.ory.sh/docs/next/ecosystem/software-architecture-philosophy).
-It implements core use cases that almost every software application needs to
-deal with: Self-service Login and Registration, Multi-Factor Authentication
-(MFA/2FA), Account Recovery and Verification, Profile, and Account Management.
+[Ory Kratos](https://github.com/ory/kratos) is an API-first Identity and User Management system that is built according to
+[cloud architecture best practices](https://www.ory.sh/docs/next/ecosystem/software-architecture-philosophy). It implements core
+use cases that almost every software application needs to deal with: Self-service Login and Registration, Multi-Factor
+Authentication (MFA/2FA), Account Recovery and Verification, Profile, and Account Management.
 
 ### Ory Hydra: OAuth2 & OpenID Connect Server
 
-[Ory Hydra](https://github.com/ory/hydra) is an OpenID Certified™ OAuth2 and
-OpenID Connect Provider which easily connects to any existing identity system by
-writing a tiny "bridge" application. Gives absolute control over user interface
-and user experience flows.
+[Ory Hydra](https://github.com/ory/hydra) is an OpenID Certified™ OAuth2 and OpenID Connect Provider which easily connects to any
+existing identity system by writing a tiny "bridge" application. Gives absolute control over user interface and user experience
+flows.
 
 ### Ory Oathkeeper: Identity & Access Proxy
 
-[Ory Oathkeeper](https://github.com/ory/oathkeeper) is a BeyondCorp/Zero Trust
-Identity & Access Proxy (IAP) with configurable authentication, authorization,
-and request mutation rules for your web services: Authenticate JWT, Access
-Tokens, API Keys, mTLS; Check if the contained subject is allowed to perform the
-request; Encode resulting content into custom headers (`X-User-ID`), JSON Web
-Tokens and more!
+[Ory Oathkeeper](https://github.com/ory/oathkeeper) is a BeyondCorp/Zero Trust Identity & Access Proxy (IAP) with configurable
+authentication, authorization, and request mutation rules for your web services: Authenticate JWT, Access Tokens, API Keys, mTLS;
+Check if the contained subject is allowed to perform the request; Encode resulting content into custom headers (`X-User-ID`), JSON
+Web Tokens and more!
 
 ### Ory Keto: Access Control Policies as a Server
 
-[Ory Keto](https://github.com/ory/keto) is a policy decision point. It uses a
-set of access control policies, similar to AWS IAM Policies, in order to
-determine whether a subject (user, application, service, car, ...) is authorized
-to perform a certain action on a resource.
+[Ory Keto](https://github.com/ory/keto) is a policy decision point. It uses a set of access control policies, similar to AWS IAM
+Policies, in order to determine whether a subject (user, application, service, car, ...) is authorized to perform a certain action
+on a resource.
 
 <!--END ECOSYSTEM-->
 

internal/check/handler.go

@@ -39,7 +39,7 @@ func NewHandler(d handlerDependencies) *Handler {
 
 const (
 	RouteBase        = "/relation-tuples/check"
-	OpenAPIRouteBase = "/relation-tuples/check/openapi"
+	OpenAPIRouteBase = RouteBase + "/openapi"
 )
 
 func (h *Handler) RegisterReadRoutes(r *x.ReadRouter) {
@@ -93,7 +93,6 @@ type getCheckRequest struct {
 //     Responses:
 //       200: getCheckResponse
 //       400: genericError
-//       403: getCheckResponse
 //       500: genericError
 func (h *Handler) getCheckNoStatus(w http.ResponseWriter, r *http.Request, _ httprouter.Params) {
 	allowed, err := h.getCheck(r.Context(), r.URL.Query())
@@ -104,6 +103,25 @@ func (h *Handler) getCheckNoStatus(w http.ResponseWriter, r *http.Request, _ htt
 	h.d.Writer().Write(w, r, &RESTResponse{Allowed: allowed})
 }
 
+// swagger:route GET /relation-tuples/check read getCheckMirrorStatus
+//
+// Check a relation tuple
+//
+// To learn how relation tuples and the check works, head over to [the documentation](../concepts/relation-tuples.mdx).
+//
+//     Consumes:
+//     -  application/x-www-form-urlencoded
+//
+//     Produces:
+//     - application/json
+//
+//     Schemes: http, https
+//
+//     Responses:
+//       200: getCheckResponse
+//       400: genericError
+//       403: getCheckResponse
+//       500: genericError
 func (h *Handler) getCheckMirrorStatus(w http.ResponseWriter, r *http.Request, _ httprouter.Params) {
 	allowed, err := h.getCheck(r.Context(), r.URL.Query())
 	if err != nil {
@@ -150,7 +168,6 @@ func (h *Handler) getCheck(ctx context.Context, q url.Values) (bool, error) {
 //     Responses:
 //       200: getCheckResponse
 //       400: genericError
-//       403: getCheckResponse
 //       500: genericError
 func (h *Handler) postCheckNoStatus(w http.ResponseWriter, r *http.Request, _ httprouter.Params) {
 	allowed, err := h.postCheck(r.Context(), r.Body, r.URL.Query())
@@ -161,6 +178,25 @@ func (h *Handler) postCheckNoStatus(w http.ResponseWriter, r *http.Request, _ ht
 	h.d.Writer().Write(w, r, &RESTResponse{Allowed: allowed})
 }
 
+// swagger:route POST /relation-tuples/check read postCheckMirrorStatus
+//
+// Check a relation tuple
+//
+// To learn how relation tuples and the check works, head over to [the documentation](../concepts/relation-tuples.mdx).
+//
+//     Consumes:
+//     -  application/json
+//
+//     Produces:
+//     - application/json
+//
+//     Schemes: http, https
+//
+//     Responses:
+//       200: getCheckResponse
+//       400: genericError
+//       403: getCheckResponse
+//       500: genericError
 func (h *Handler) postCheckMirrorStatus(w http.ResponseWriter, r *http.Request, _ httprouter.Params) {
 	allowed, err := h.postCheck(r.Context(), r.Body, r.URL.Query())
 	if err != nil {