Page tree
Skip to end of metadata
Go to start of metadata


OpenAPI 3

Quickstart

https://github.com/ivan1405/binary-mindset-api-first-tutorial

Designing a Yaml using editor.swagger.io

https://editor.swagger.io/

Spring boot openapi generator

https://github.com/OpenAPITools/openapi-generator

https://github.com/OpenAPITools/openapi-generator#12---artifacts-on-maven-central

https://openapi-generator.tech/docs/generators/spring/

Generate Spring Boot Controller from Openapi yaml

Implement ApiDelegateImpl Service

The default method on the generated service delegate will generate an HttpStatus.NOT_IMPLEMENTED response.  This response will allow for a minimal runtime/swagger.  It is up to the developer (us) to provide a custom implementation of the service - which spring will find and inject.  We override the default method.

@Service
public class HealthApiDelegateService implements HealthApiDelegate {

	@Override
	public ResponseEntity<Health> health() {
		Health health = new Health();
		health.setKey("status");
		health.setValue("ok");
		return ResponseEntity.ok(health);
	}
}



Add Swagger 2 to an existing Maven Java project

Example: 

REF-15 - Getting issue details... STATUS
https://github.com/obrienlabs/refarch/pull/3
https://github.com/obrienlabs/magellan/commit/60fbadbc24b347cdbe69b6eb336b858359579492
https://gitlab.com/refarch/reference/-/commit/0fd7e3e1281497fd3ed5a0eeb9b5b13530c774d5

Add the following to your pom.xml

	<dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.9.2</version>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.9.2</version>
    </dependency>


Add the following Spring Configuration bean to your Spring Boot project

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
	
	@Bean
	public Docket api() {
		return new Docket(DocumentationType.SWAGGER_2)
				.select()
				.apis(RequestHandlerSelectors.any())
				.paths(PathSelectors.any())
				.build();			
	}
}


Test swagger live site

http://localhost:8080/nbi/swagger-ui.html

Swagger Live Generation and Servlet Filters

Be careful when running filters on all incoming content - as it will disrupt the live swagger site.  For example

import org.springframework.core.annotation.Order;
import org.springframework.stereotype.Component;

@Component
@Order(1)
public class Base64Filter implements Filter {
 


Exporting Swagger to OpenAPI 3

Exporting JAXB to OpenAPI 3

Json Schemas

JSON-LD

http://niem.github.io/json/reference/json-ld/context/


Links

https://github.com/WhiteHouse/api-standards

https://hub.docker.com/u/swaggerapi

https://github.com/OpenAPITools/openapi-generator/blob/master/modules/openapi-generator-maven-plugin/README.md

https://www.blazemeter.com/blog/how-to-check-swagger-docs-in-jenkins-with-the-validator-badge-tool/


  • No labels