Совет по Swagger API

Я создаю API с помощью служб SpringBoot и Spring REST с использованием Java 8. Я только что открыл для себя Swagger API и теперь хочу сделать свой API Swagger совместимым.

Насколько я читал, Swagger - это инструмент для документирования вашего APIS, но он также предоставляет функции для генерации клиентского и серверного кода из спецификации (swagger.json в v2), помимо приятного веб-интерфейса для взаимодействия с вашим API.

Теперь я хотел бы получить несколько рекомендаций о том, как действовать, учитывая, что у меня уже есть существующий API, по крайней мере, с 15 контроллерами. Должен ли я написать всю спецификацию с нуля (файл swagger.json), а затем использовать codegen для генерации кода сервера (контроллеры и объекты)? Или было бы лучше аннотировать существующие контроллеры аннотациями Swagger-core, а затем сгенерировать оттуда спецификацию json?

Второй вариант имеет для меня больше смысла, но я не знаю, как мы генерируем спецификацию swagger.json из существующего API (если возможно).

Не могли бы вы дать мне несколько рекомендаций по этому поводу?

Спасибо


java api swagger swagger-ui spring-rest
person fgonzalez    schedule 16.12.2015    source источник
comment
Вместо этого вы можете рассмотреть Spring REST Docs, который тесно интегрируется со Spring MVC и создает документацию из ваших тестирование.   -  person chrylis -cautiouslyoptimistic-    schedule 16.12.2015
comment
Спасибо! Я тогда посмотрю :)   -  person fgonzalez    schedule 16.12.2015
comment
Хорошая черта Swagger заключается в том, что вы можете взаимодействовать с API прямо из документации (swagger-ui). Есть ли что-то подобное с использованием Spring Rest Docs?   -  person fgonzalez    schedule 16.12.2015

Ответы (2)


arrow_upward
8
arrow_downward

Интегрировать чванство с весенним ботинком или весенним облаком очень просто.

Только несколько аннотаций к вашим существующим REST API, и он автоматически сгенерирует для вас всю спецификацию swagger. Swagger определенно является одним из самых популярных фреймворков документации REST API.

зависимости pom.xml

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.2.2</version>
    <scope>compile</scope>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.2.2</version>
    <scope>compile</scope>
</dependency>

определить информацию об API в приложении Springboot

@Bean
public Docket newsApi() {
    return new Docket(DocumentationType.SWAGGER_2)
            .groupName("springboot")
            .apiInfo(apiInfo())
            .select()
            .paths(regex("/.*"))
            .build();
}
 
private ApiInfo apiInfo() {
    return new ApiInfoBuilder()
            .title("SpringBoot REST API with Swagger")
            .description("SpringBoot REST API with Swagger")
            .termsOfServiceUrl("http://www-03.ibm.com/software/sla/sladb.nsf/sla/bm?Open")
            .contact("sanket**@au1.ibm.com")
            .license("Apache License Version 2.0")
            .licenseUrl("https://github.com/IBM-Bluemix/news-aggregator/blob/master/LICENSE")
            .version("2.0")
            .build();
}

Аннотации

@EnableSwagger2 для вашего класса приложения

Аннотируйте свои REST API

Что-то вроде этого

@RequestMapping(value = "/operate/add/{left}/{right}", method = RequestMethod.GET, produces = "application/json")
@ApiOperation(value = "addNumbers", nickname = "addNumbers")
@ApiResponses(value = { @ApiResponse(code = 200, message = "Success", response = Result.class),
        @ApiResponse(code = 401, message = "Unauthorized"), 
        @ApiResponse(code = 500, message = "Failure") })
public Result add(@PathVariable("left") int left, @PathVariable("right") int right) {

Вы сделали. Пользовательский интерфейс Swagger включен по умолчанию, и вы также можете получить доступ к спецификациям Swagger в формате JSON. Доступ http://localhost:12001/swagger-ui.html#/

Дополнительные сведения см. В этой базе кода: https://github.com/sanketsw/SpringBoot_REST_API

person Sacky San    schedule 10.03.2016

arrow_upward
0
arrow_downward

Я понимаю, что это поздно, но вот альтернатива, которую вы должны рассмотреть: вместо генерации описания OpenAPI API из вашей реализации вы можете вручную написать описание OpenAPI API, а затем попросить вашу реализацию прочитать его во время запуска и автоматически настроить его маршрутизация URL, типы ответов и т. д. соответственно.

Т.е. генерировать реализацию из документации, а не создавать документацию из реализации.

Понятия не имею, насколько это возможно весной (извините). С Python и WSGI это было несложно.

Хорошая это идея или нет - решать только вам.

person AnotherSmellyGeek    schedule 03.02.2018