Saturday, July 15, 2023

Coursera and verifying ID with Persona

It was a total nightmare being able to verify my Id with Coursera. Coursera will not issue a certificate unless you verify your Id. It turned out that Coursera/Persona doesn't recognize my Italian Paper Id - probably because it's not in Credic Card format. And It doesn't recognize my Residence Permit in Switzerland. After a LOT of attempts it accepted my Swiss Driving License. It's totally disappointing that they don't allow you to tal to a human, all is determined by these automated procedures. If you think that the AI-dominated world will be a Paradise, think twice, an Algorythm will decide of your life. Worst of the orwellian nightmares.

springdoc-openapi-maven-plugin

I will guide you to build a simple RESTful web service using Spring Boot, and then we will generate the OpenAPI 3.0 documentation using the springdoc-openapi-maven-plugin. Step 1: Setup Spring Boot Project Create a new Spring Boot project. You can use Spring Initializr (https://start.spring.io/) for easy bootstrapping of your project. For the dependencies, select: Web JPA H2 (for simplicity, we're using an in-memory database) Springdoc OpenAPI UI Step 2: Create the application.properties In src/main/resources/application.properties, add the following configuration:
spring.datasource.url=jdbc:h2:mem:testdb
spring.datasource.driverClassName=org.h2.Driver
spring.datasource.username=sa
spring.datasource.password=password
spring.jpa.database-platform=org.hibernate.dialect.H2Dialect
Step 3: Create a simple Entity Create a Student class in your project:
import javax.persistence.Entity;
import javax.persistence.Id;

@Entity
public class Student {

    @Id
    private String id;
    private String name;

    // getters and setters
}
Step 4: Create a JPA Repository Create an interface StudentRepository that extends JpaRepository:
import org.springframework.data.jpa.repository.JpaRepository;

public interface StudentRepository extends JpaRepository<Student, String> {}
Step 5: Create a REST Controller Create a StudentController class:
import org.springframework.web.bind.annotation.*;

import java.util.List;

@RestController
@RequestMapping("/api/students")
public class StudentController {

    private final StudentRepository repository;

    public StudentController(StudentRepository repository) {
        this.repository = repository;
    }

    @GetMapping
    public List<Student> getAllStudents() {
        return repository.findAll();
    }

    @PostMapping
    public Student newStudent(@RequestBody Student newStudent) {
        return repository.save(newStudent);
    }
}
Step 6: Generating OpenAPI 3.0 docs Add the springdoc-openapi-maven-plugin to your pom.xml:
  
<plugin>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-maven-plugin</artifactId>
    <version>1.5</version>
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
            <phase>compile</phase>
            <configuration>
                <apiDocsUrl>http://localhost:8080/v3/api-docs</apiDocsUrl>
                <outputFileName>openapi.json</outputFileName>
                <outputDir>${project.build.directory}</outputDir>
            </configuration>
        </execution>
    </executions>
</plugin>
This will generate an openapi.json file in your target directory whenever you compile your project. Now when you run your application and go to http://localhost:8080/swagger-ui.html, you should see the OpenAPI UI with your API documented. You can use the UI to send requests and see the responses. Remember to start your application before generating the documentation, because the plugin makes an actual HTTP request to the /v3/api-docs endpoint to generate the OpenAPI specification. Please be aware that as of my knowledge cut-off in September 2021, the above mentioned plugin and setup were in use. Please ensure that you're using up-to-date versions and configurations by checking the official documentation.

openapi-generator-maven-plugin

The openapi-generator-maven-plugin is a plugin for the Apache Maven project management tool, which is used to build and manage projects written in Java and other languages. This plugin specifically aids in the generation of API clients, server stubs, API documentation, and configuration from an OpenAPI Specification (formerly known as the Swagger Specification). An OpenAPI Specification is a standard, language-agnostic way of describing HTTP-based APIs, allowing both humans and machines to understand the capabilities of a service without having to read the source code or access documentation. Here is an example of how the openapi-generator-maven-plugin might be configured in your pom.xml:

<build>
  <plugins>
    <plugin>
      <groupId>org.openapitools</groupId>
      <artifactId>openapi-generator-maven-plugin</artifactId>
      <version>4.3.1</version> <!-- use the latest version available -->
      <executions>
        <execution>
          <goals>
            <goal>generate</goal>
          </goals>
          <configuration>
            <inputSpec>${project.basedir}/src/main/resources/api.yaml</inputSpec>
            <generatorName>java</generatorName>
            <configOptions>
              <sourceFolder>src/gen/java/main</sourceFolder>
            </configOptions>
          </configuration>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

In the configuration above, the inputSpec tag is used to specify the location of the API specification file. The generatorName tag is used to specify the language of the generated code, in this case, Java. The configOptions tag is used to specify various options for the generated code, such as its location within the project. After this plugin is set up and the project is built (for instance, with mvn install), the API clients, server stubs, and other generated code are produced automatically based on the API specification file. This can significantly streamline the development process when working with APIs. Please note the plugin version in the example is hypothetical and might be outdated at the time of your query. You should always try to use the latest available version.