|
1 | | -Dear Reader : Thanks for selecting PKMST swagger code generation toolkit for starting your microservice journey. |
2 | | -We believe the hard work we put into this framework will help you kick start your journey sooner and you will find it |
3 | | -easy to scale your service to enterprise grade. Another great thing is you don't need to enable all capabilities as you start, |
4 | | -but can enable as your microservice capabilities needs to be extended to meet strict enterprise standards. |
| 1 | +# Swagger Jersey generated server |
5 | 2 |
|
6 | | -PKMST feature set. |
7 | | -a)Read the Swagger supplied and will create a maven project |
8 | | -b)Create basic controller based on rest verb and path configured in swagger |
9 | | -c)generate default unit test cose using junit |
10 | | -d)generate all needed dependency needed to run the microservice on local |
11 | | -e)generate a default manifest file that allows you to push code to cloudfoundry instance ( eg pcf , ibm bluemix etc) |
| 3 | +## Overview |
| 4 | +This server was generated by the [swagger-codegen](https://github.com/swagger-api/swagger-codegen) project. By using the |
| 5 | +[OpenAPI-Spec](https://github.com/swagger-api/swagger-core/wiki) from a remote server, you can easily generate a server stub. This |
| 6 | +is an example of building a swagger-enabled JAX-RS server. |
12 | 7 |
|
13 | | -As you mature your knowledge with pkmst, you can leverage vendor extensions feature that will allow you to supply specific configuration |
14 | | -in your swagger and generate respective configuration that will |
15 | | -f)Allow you integrate with registry server (Example Eureka) |
16 | | -g)Allow you to integrate with tracing server (Example Zipkin) |
17 | | -h)Allow you to capture log in your microservice and send to Log management server (Ex ELK or splunk) |
18 | | -i)Allow you to configure Oauth2 security based authorization for your microservice |
| 8 | +This example uses the [JAX-RS](https://jax-rs-spec.java.net/) framework. |
19 | 9 |
|
20 | | - Additonal Features |
21 | | - j)generate sample cucumber file and dependency to drive your Behaviour driven development. |
22 | | - k)generate gatling based perfromance test , which can be excuted via build pipeline like jenkins etc. |
23 | | - |
24 | | - |
25 | | -Working: |
26 | | -Using swagger specification you can convert any definition to spring boot microservice. |
27 | | -It has the integration with the below services: |
28 | | -eureka registry, zipkin , spring boot admin, circuit breaker. |
| 10 | +To run the server, please execute the following: |
29 | 11 |
|
30 | | -By default only the circuit breaker annotation is enabled. But one has to write the fallback method. The needed dependency for it is also been enabled. To generate the integration and |
31 | | -related configuration for eureka, zipkin, spring boot admin one has two options: |
| 12 | +``` |
| 13 | +mvn clean package jetty:run |
| 14 | +``` |
32 | 15 |
|
33 | | -1) When generating from UI one has to provide vendor extensions inside the swagger specification as below: |
34 | | -swagger: "2.0" |
35 | | -info: |
36 | | - description: "This is a sample Product Catalogue Server.\ |
37 | | - \ For this sample, you can use the api key `special-key` to test the authorization\ |
38 | | - \ filters." |
39 | | - version: "1.0.0" |
40 | | - x-codegen: |
41 | | - eurekaUri: "http://localhost:8080" |
42 | | - zipkinUri: "http://localhost:9411" |
43 | | - springBootAdminUri: "http://localhost:8000" |
44 | | - pkmstInterceptor: "true" |
45 | | - |
46 | | -PLease note the vendor extensions are inside the info tag of the swagger specification. All the tags are case sensitive. Once given all the related configuration and the dependency |
47 | | -will be enabled. |
| 16 | +You can then view the swagger listing here: |
48 | 17 |
|
49 | | -2) When generating from the maven plugin one has to provide configuration inside pom as below: |
50 | | -inside the swagger codegen maven plugin under the configuration section |
| 18 | +``` |
| 19 | +http://localhost:8008/v2/swagger.json |
| 20 | +``` |
51 | 21 |
|
52 | | - <configuration> |
53 | | - <inputSpec>product-swagger.yaml</inputSpec> |
54 | | - <language>pkmst</language> |
55 | | - <output>${project.build.directory}/generated-sources</output> |
56 | | - <configOptions> |
57 | | - <groupId>com.prokarma</groupId> |
58 | | - <artifactId>product-catalogue</artifactId> |
59 | | - <artifactVersion>1.0</artifactVersion> |
60 | | - <basePackage>com.prokarma.pkmst</basePackage> |
61 | | - <serviceName>ProductCatalogue</serviceName> |
62 | | - <eurekaUri></eurekaUri> |
63 | | - <zipkinUri>http://localhost:9411</zipkinUri> |
64 | | - <springBootAdminUri>http://localhost:4588</springBootAdminUri> |
65 | | - <pkmstInterceptor>true</pkmstInterceptor> |
66 | | - </configOptions> |
67 | | - </configuration> |
68 | | - |
69 | | - The project has three profiles local, dev, dev-config which can be configured accordingly. Once you have provided the uris you can see the necessary configurations generated inside the local and the dev |
70 | | - yml files. dev-config is for the config server if you want to use.(also enable the dependency for the config server inside the pom) |
71 | | - |
72 | | - [Note: one has to run the zipkin, eureka, spring boot admin servers to be able to connect from the app. This project assumes that you have all the servers |
73 | | - up and running.] |
74 | | - |
75 | | - Also provided are the middleware handlers: |
76 | | - |
77 | | -1) traceInterceptor:is an id passed in from client and will be unique with an application context. The id will be passed into the backend and return to the consumer for transaction tracing. |
78 | | - |
79 | | -2) correlationInterceptor:generates a UUID in the first API/service and pass it to all other APIs/services in the call tree for tracking purpose. |
80 | | - |
81 | | -3) rateLimitInterceptor:is a rate limiting handler to limit number of concurrent requests on the server. Once the limit is reached, subsequent requests will be queued for later execution. The size of the queue is configurable. |
82 | | - |
83 | | -4) auditInterceptor: audit logs most important info about request and response into audit.log in JSON format with config file that controls which fields to be logged |
84 | | - |
85 | | -5) bodyInterceptor:s a body parser middleware that is responsible for parsing the content of the request based on Content-Type in the request header. |
86 | | - |
87 | | -To be able to generate the handlers and the necessary configurations one has to provide the pkmstInterceptor key inside the vendor extensions or through |
88 | | -the maven plugin. |
89 | | -Once provided all the handlers are registered in the interceptor registry and can be enabled or disabled through the configuration provided inside |
90 | | -the application yml as below: |
91 | | -interceptor: |
92 | | - enable: |
93 | | - audit: true |
94 | | - body: true |
95 | | - rateLimit: true |
96 | | - traceability: true |
97 | | - correlation: true |
98 | | - |
99 | | -For testing we have placeholders for junit test class, integration test class, cucumber sample |
100 | | -feature file(implement according to your needs), gatling load test. |
101 | | - |
102 | | -Ways to run the project: |
103 | | -1) Normal spring boot application |
104 | | - |
105 | | -2) Using Dockerfile to run in the container: |
106 | | -dockerfile will be generated inside the project by default. Image can be created using docker cli or through the maven plugin |
107 | | - |
108 | | -<build> |
109 | | - <plugins> |
110 | | - ... |
111 | | - <plugin> |
112 | | - <groupId>com.spotify</groupId> |
113 | | - <artifactId>docker-maven-plugin</artifactId> |
114 | | - <version>VERSION GOES HERE</version> |
115 | | - <configuration> |
116 | | - <imageName>example</imageName> |
117 | | - <dockerDirectory>docker</dockerDirectory> |
118 | | - <resources> |
119 | | - <resource> |
120 | | - <targetPath>/</targetPath> |
121 | | - <directory>${project.build.directory}</directory> |
122 | | - <include>${project.build.finalName}.jar</include> |
123 | | - </resource> |
124 | | - </resources> |
125 | | - </configuration> |
126 | | - </plugin> |
127 | | - ... |
128 | | - </plugins> |
129 | | -</build> |
130 | | - |
131 | | -Use manifest.yml file to push the application to the cloud. |
132 | | - |
133 | | -HttpLogging filter is provided for logging in the request and response. Can be found inside the com.prokarma.pkmst.logging package. |
134 | | -Spring security is also provided to secure the resources. Please modify according to your needs. |
135 | | - |
136 | | -First run: |
137 | | -Import the project in to the eclipse. Run the app as an spring boot application.The project will run on http://localhost:8008 |
138 | | -Swagger ui available on: |
139 | | -http://localhost:8008/swagger-ui.html |
140 | | -If all the configurations have been enabled(depending on the port) below are some of the URls to access: |
141 | | -eureka: http://localhost:8080 |
142 | | -zipkin: http://localhost:9411 |
| 22 | +Note that if you have configured the `host` to be something other than localhost, the calls through |
| 23 | +swagger-ui will be directed to that host and not localhost! |
0 commit comments