OpenAPI Code Generation and OAuth2 Resource Server

This is a demo application to generate the REST APIs with OpenAPI and protect them with OAuth2 Reousrce Server. In this demo application, we generate the customer APIs and implement them. After that we protect those APIs by configuring the OAuth2 Resource Server. To access those APIs, we have to prived the signed JWT access token which had been issued by the Authorization Server.

Please read the documents to find more details about OpenAPI Specficiation and OAuth2.0.

Prerequisites: Java8 or above

Getting Started

To install this demo application, please run the following command in a terminal window:

git clone https://github.com/hailiangxie/myopenapi_codegen_resourceserver_proj.git
cd myopenapi_codegen_resourceserver_proj

Generating APIs

To generate APIs, first we need to create an API Spec file called api.yaml and put it to src/main/reousrces/api:

openapi: 3.0.2
info:
  title: Customer - OpenAPI 3.0
  description: |-
    This is a sample Customer Server based on the OpenAPI 3.0 specification.  You can find out more about
    Swagger at [http://swagger.io](http://swagger.io).

  version: 1.0.0
externalDocs:
  description: Find out more about Swagger
  url: http://swagger.io
servers:
  - url: /api/v3
tags:
  - name: customer
    description: Everything about the customers
    externalDocs:
      description: Find out more
      url: http://swagger.io

Second we need to configure the API package in the project pom file:

<plugin>
    			<groupId>org.openapitools</groupId>
    			<artifactId>openapi-generator-maven-plugin</artifactId>
    			<version>4.2.2</version>
    			<executions>
        			<execution>
            			<goals>
                			<goal>generate</goal>
            			</goals>
            			<configuration>
                			<inputSpec>${api.spec.file}</inputSpec>
                			<output>${project.build.directory}/generated/open-api</output>
                			<generatorName>spring</generatorName>
                			<apiPackage>xie.hailiang.resourceserver.api</apiPackage>
                			<modelPackage>xie.hailiang.resourceserver.model</modelPackage>
                			<invokerPackage>xie.hailiang.resourceserver.handler</invokerPackage>
                			<modelNameSuffix>Json</modelNameSuffix>
                			<configOptions>
                    			<delegatePattern>true</delegatePattern>
                			</configOptions>
            			</configuration>
        			</execution>
    			</executions>
			</plugin>

And finally we can run the following command in a terminal window:

cd myopenapi_codegen_resourceserver_proj
./mvnw install

The customer APIs should be generated.

Implementing APIs

To implement the generated REST APIs, we need to implement the generated delegate interface CustomerApiDelegate:

@Component
public class CustomerApiDelegateImpl implements CustomerApiDelegate {
  // implement the methods declared in CustomerApiDelegate
}

Protecting APIs

To protect the generated REST APIs, we need to configure the OAuth2 Resource Server in the project:
First we add the OAuth2 and Reousrce Server dependencies to the porject pom.

<dependency>
   			<groupId>org.springframework.boot</groupId>
   			<artifactId>spring-boot-starter-oauth2-resource-server</artifactId>
		</dependency>
		<dependency>
   			<groupId>org.springframework.cloud</groupId>
   			<artifactId>spring-cloud-starter-oauth2</artifactId>
   			<version>2.2.5.RELEASE</version>
		</dependency>

Second we add the ResourceServerConfig class to enable Resource Server functionality.

@Configuration
@EnableResourceServer
public class ResourceServerConfig extends ResourceServerConfigurerAdapter {
}

And third we need to configure the cryptographic public key in src/main/resources/application.yml.
The public key was generated by calling the endpoint /oauth/token_key from the Authroization Server.

jwtkey: 
  publicKey: "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"

The Resource Server protects the APIs by validating that if the client has a valid JWT access token.

Run the Application

To run this demo application, please run the following command in a terminal window:

cd myopenapi_codegen_resourceserver_proj
./mvnw spring-boot:run

After everything starts, we should be able to test the Application.

Test

Now we shoulbe be able to test the customer REST APIs. To view the API docs and test the APIs we can open the swagger-ui by accessing the url http://localhost:8091/swagger-ui.html in the web browser. And also we can test the APIs with other tools (e.g., curl, postman). For example, we test the API /api/v3/customer to add a new customer.

• Access the API http://localhost:8091/api/v3/customer without a token:

Request Method: Post
Accept: application/json
ContentType: application/json
Content: The new customer json string
Expect: It should return status 401 Unauthorized

• Access the API http://localhost:8091/api/v3/customer without an invalid token:

Request Method: Post
Header: Authorization: Bearer itisaninvalidtoken
Accept: application/json
ContentType: application/json
Content: The new customer json string
Expect: It should return status 401 Unauthorized

• Access the API http://localhost:8091/api/v3/customer with a valid token (by calling the endpoint /oauth/token from the Authorization Server):

Request Method: Post
Header: Authorization: Bearer <Valid token>
Accept: application/json
ContentType: application/json
Content: The new customer json string
Expect: It should return status 200 and the new customer created

See Also

The following guides may also be helpful:

• Swagger UI
• JSON Web Tokens