mirror of https://github.com/goharbor/harbor.git
Update Swagger 's readme.md (#22087)
Build Package Workflow / BUILD_PACKAGE (push) Waiting to run
Details
Code scanning - action / CodeQL-Build (push) Waiting to run
Details
CI / UTTEST (push) Has been cancelled
Details
CI / APITEST_DB (push) Has been cancelled
Details
CI / APITEST_DB_PROXY_CACHE (push) Has been cancelled
Details
CI / APITEST_LDAP (push) Has been cancelled
Details
CI / OFFLINE (push) Has been cancelled
Details
CI / UI_UT (push) Has been cancelled
Details
Build Package Workflow / BUILD_PACKAGE (push) Waiting to run
Details
Code scanning - action / CodeQL-Build (push) Waiting to run
Details
CI / UTTEST (push) Has been cancelled
Details
CI / APITEST_DB (push) Has been cancelled
Details
CI / APITEST_DB_PROXY_CACHE (push) Has been cancelled
Details
CI / APITEST_LDAP (push) Has been cancelled
Details
CI / OFFLINE (push) Has been cancelled
Details
CI / UI_UT (push) Has been cancelled
Details
Enhance readability of swagger Readme.md file by fixing minor errors Signed-off-by: chethanm99 <chethanm1399@gmail.com>
This commit is contained in:
parent
ec9d13d107
commit
b647032747
|
@ -4,16 +4,16 @@ In Stratoscale, we really like the idea of API-first services, and we also reall
|
|||
We saw the go-swagger library, and thought that most of it can really help us. Generating code from
|
||||
swagger files is a big problem with a lot of corner cases, and go-swagger is doing great job.
|
||||
|
||||
The one thing that we felt missing, is customization of the server to run with our design principles:
|
||||
The one thing that we felt missing was customization of the server to run with our design principles:
|
||||
|
||||
* Custom `main` function
|
||||
* Dependency injection
|
||||
* Limited scopes with unit testing.
|
||||
* Limited scope with unit testing.
|
||||
|
||||
Also:
|
||||
|
||||
* Adding you functions to the generated `configure_swagger_*.go` seems to be a burden.
|
||||
* Lack of Interface that the service implement.
|
||||
* Adding your functions to the generated `configure_swagger_*.go` seems to be a burden.
|
||||
* Lack of Interface that the service implements.
|
||||
* Complicated and custom http clients and runtime.
|
||||
|
||||
Those are the changes that this contributor templates are providing:
|
||||
|
@ -22,7 +22,7 @@ Those are the changes that this contributor templates are providing:
|
|||
|
||||
### The new `restapi` package exposes interfaces
|
||||
|
||||
* Those interfaces can implemented by the developer and are the business logic of the service.
|
||||
* Those interfaces can be implemented by the developer and are the business logic of the service.
|
||||
* The implementation of those is extensible.
|
||||
* The implementation is separated from the generated code.
|
||||
|
||||
|
@ -32,8 +32,8 @@ The `restapi.Handler` (see [example](./example/restapi/configure_swagger_petstor
|
|||
a standard `http.Handler`
|
||||
|
||||
* Given objects that implements the business logic, we can create a simple http handler.
|
||||
* This handler is standard go http.Handler, so we can now use any other middleware, library, or framework
|
||||
that support it.
|
||||
* This handler is a standard go http.Handler, so we can now use any other middleware, library, or framework
|
||||
that supports it.
|
||||
* This handler is standard, so we understand it better.
|
||||
|
||||
## Client
|
||||
|
@ -57,7 +57,7 @@ In the [example package](https://github.com/Stratoscale/swagger/tree/master/exam
|
|||
|
||||
### [restapi](https://github.com/Stratoscale/swagger/tree/master/example/restapi)
|
||||
|
||||
This package is autogenerated and contains the server routing and parameters parsing.
|
||||
This package is autogenerated and contains the server routing and parameter parsing.
|
||||
|
||||
The modified version contains `restapi.PetAPI` and `restapi.StoreAPI` which were auto generated.
|
||||
|
||||
|
@ -116,7 +116,7 @@ Let's look how we use this generated code to build our server.
|
|||
### [internal](https://github.com/Stratoscale/swagger/tree/master/example/internal)
|
||||
|
||||
The `internal` package is **not** auto generated and contains the business logic of our server.
|
||||
We can see two structs that implements the `restapi.PetAPI` and `restapi.StoreAPI` interfaces,
|
||||
We can see two structs that implement the `restapi.PetAPI` and `restapi.StoreAPI` interfaces,
|
||||
needed to make our server work.
|
||||
|
||||
When adding or removing functions from our REST API, we can just add or remove functions to those
|
||||
|
@ -189,7 +189,7 @@ type SwaggerPetstore {
|
|||
}
|
||||
```
|
||||
|
||||
Those fields are objects, which implements interfaces declared in the [pet](./example/client/pet) and
|
||||
Those fields are objects, which implement interfaces declared in the [pet](./example/client/pet) and
|
||||
[store](./example/client/store) packages:
|
||||
|
||||
For example:
|
||||
|
@ -234,7 +234,7 @@ security:
|
|||
|
||||
The securityDefinitions section defines different security types that your application can handle.
|
||||
The supported types by go-swagger are:
|
||||
* `apiKey` - token that should be able to processed.
|
||||
* `apiKey` - token that should be able to be processed.
|
||||
* `oauth2` - token and scopes that should be processed.
|
||||
* and `basic` - user/password that should be processed.
|
||||
|
||||
|
@ -253,7 +253,7 @@ paths:
|
|||
- token: [admin]
|
||||
```
|
||||
|
||||
Here we overridden the scope of token in the POST /pets URL so that only admin can use this API.
|
||||
Here we have overridden the scope of the token in the POST /pets URL so that only admin can use this API.
|
||||
|
||||
Let's see how we can use this functionality.
|
||||
|
||||
|
@ -289,14 +289,14 @@ type Config struct {
|
|||
|
||||
This one is a custom defined function that gets the request and can return an error.
|
||||
If the returned error is not nil, and 403 HTTP error will be returned to the client - here the policy
|
||||
enforcement comes to place.
|
||||
enforcement comes into play.
|
||||
There are two things that this function should be aware of:
|
||||
|
||||
1. The user - it can retrieve the user information from the context: `ctx.Value(restapi.AuthKey).(MyUserType)`.
|
||||
Usually, a server will have a function for extracting this user information and returns a concrete
|
||||
type which could be used by all the routes.
|
||||
2. The route - it can retrieve the route using the go-swagger function: `middleware.MatchedRouteFrom(*http.Request)`.
|
||||
So no need to parse URL and test the request method.
|
||||
So no need to parse the URL and test the request method.
|
||||
This route struct contains the route information. If for example, we want to check the scopes that were
|
||||
defined for the current route in the swagger.yaml we can use the code below:
|
||||
|
||||
|
|
Loading…
Reference in New Issue