Я играл с Swagger Codegen для проекта Springboot. Теперь я могу автоматически генерировать клиентский код в java, игнорировать генерацию моделей данных (импортировать свой собственный в swagger-codegen-maven-plugin через importMapping). Кроме того, я также могу:
- указывать теги непосредственно в коде Springboot для организации контракта openapi,
- использовать аннотацию @Operation для указания имен методов,
- используйте аннотацию @ApiResponses для подробного описания ожидаемых кодов и описаний ответов и т. Д. c.
Пример ниже:
@RestController
@RequestMapping(value="/api/external/")
@Tag(name = "addResources", description = "The Add Resources API")
public class ControllerAddResources {
private final ServiceInterAddResources externalSources;
public ControllerAddResources(
ServiceInterAddResources externalSources){
this.externalSources = externalSources;
}
@Operation(operationId="importDataV3", summary = "Import Data V3", description = "Import a Data V3 file from source", tags = { "addResources" })
@PostMapping(path="/{source}/datav3", consumes = {MediaType.MULTIPART_FORM_DATA_VALUE})
public @ResponseBody String importDataV3(
@PathVariable String source,
MultipartFile file) throws ExceptionInvalidDataV3, IOException{
return externalSources.importDataV3(source, file);
}
Все это встроено в контракт openapi, который затем используется codegen для генерации клиентской библиотеки (в данном случае я использую resttemplate), как показано ниже:
@javax.annotation.Generated(value = "io.swagger.codegen.v3.generators.java.JavaClientCodegen", date = "2020-03-05T12:15:11.537Z[Europe/Lisbon]")@Component("com.xxx.connector.api.AddResourcesApi")
public class AddResourcesApi {
private ApiClient apiClient;
public AddResourcesApi() {
this(new ApiClient());
}
@Autowired
public AddResourcesApi(ApiClient apiClient) {
this.apiClient = apiClient;
}
public ApiClient getApiClient() {
return apiClient;
}
public void setApiClient(ApiClient apiClient) {
this.apiClient = apiClient;
}
/**
* Import Data V3
* Import a Data V3 file from source
* <p><b>412</b> - default response
* <p><b>409</b> - default response
* <p><b>200</b> - default response
* @param source The source parameter
* @param file The file parameter
* @return String
* @throws RestClientException if an error occurs while attempting to invoke the API
*/
public String importDataV3(String source, File file) throws RestClientException {
Object postBody = null;
// verify the required parameter 'source' is set
if (source == null) {
throw new HttpClientErrorException(HttpStatus.BAD_REQUEST, "Missing the required parameter 'source' when calling importDataV3");
}
// create path and map variables
final Map<String, Object> uriVariables = new HashMap<String, Object>();
uriVariables.put("source", source);
String path = UriComponentsBuilder.fromPath("/api/external/{source}/datav3").buildAndExpand(uriVariables).toUriString();
final MultiValueMap<String, String> queryParams = new LinkedMultiValueMap<String, String>();
final HttpHeaders headerParams = new HttpHeaders();
final MultiValueMap<String, Object> formParams = new LinkedMultiValueMap<String, Object>();
if (file != null)
formParams.add("file", new FileSystemResource(file));
final String[] accepts = {
"*/*", "application/json"
};
final List<MediaType> accept = apiClient.selectHeaderAccept(accepts);
final String[] contentTypes = {
"multipart/form-data"
};
final MediaType contentType = apiClient.selectHeaderContentType(contentTypes);
String[] authNames = new String[] { };
ParameterizedTypeReference<String> returnType = new ParameterizedTypeReference<String>() {};
return apiClient.invokeAPI(path, HttpMethod.POST, queryParams, postBody, headerParams, formParams, accept, contentType, authNames, returnType);
}
В сгенерированных источниках codegen также включает в себя строительные леса для тестов junit, как показано ниже:
/**
* API tests for AddResourcesApi
*/
@Ignore
public class AddResourcesApiTest {
private final AddResourcesApi api = new AddResourcesApi();
/**
* Import Data V2
*
* Import an Data V2 file from source
*
* @throws ApiException
* if the Api call fails
*/
@Test
public void imporDataV2Test() {
String source = null;
File file = null;
String response = api.importDataV2(source, file);
// TODO: test validations
}
/**
* Import Data V3
*
* Import an Data V3 file from source [%source%]
*
* @throws ApiException
* if the Api call fails
*/
@Test
public void importDataV3Test() {
String source = null;
File file = null;
String response = api.importDataV3(source, file);
// TODO: test validations
}
}
Однако код проверки пусто, как и ожидалось. Поскольку клиент постоянно генерируется в среде CI / CD и развертывается в системе управления зависимостями, которую я использую внутри (Artifactory), это лишает смысла писать тесты вручную каждый раз, когда я выполняю codegen.
Есть ли способ указания кода валидации (или реквизитов валидации) напрямую с использованием аннотаций java (или механизма шаблонов) на уровне проекта Springboot? Это позволит полностью автоматизировать создание клиентской библиотеки с включенным тестированием.