3

我正在使用 Java 8 构建使用 SpringBoot 和 Spring REST 服务的 API。我刚刚发现了 Swagger API，现在我想让我的 API Swagger 兼容。

据我所知，Swagger 是一个记录 APIS 的工具，但还提供了从规范（v2 中的 swagger.json）生成客户端和服务器代码的功能，此外还有一个很好的 Web 界面来与你的 API 交互。

现在，鉴于我已经有一个包含至少 15 个控制器的现有 API，我想要一些关于如何进行的建议。我是否应该从头开始编写整个规范（swagger.json 文件），然后使用 codegen 生成服务器代码（控制器和对象）？或者最好用 Swagger-core 注释来注释现有的控制器，然后从那里生成一个 json 规范？

第二个选择对我来说更有意义，但我不知道我们如何从现有 API 生成 swagger.json 规范（如果可能的话）。

你能给我一些关于它的建议吗？

谢谢

4

2 回答 2

8

Integrating swagger with spring boot or spring cloud is very easy.

Only a few annotations to your existing REST APIs and it will generate whole swagger specification for you automatically. Swagger is definitely one of the most popular REST API documentation frameworks.

pom.xml dependencies

<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>

define api info in your springboot application

@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();
}

Annotations

@EnableSwagger2 for your Application class

Annotate your REST APIs

Something like this

@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) {

You are done. The Swagger UI is included by default and you can also access the swagger specs in JSON format. Access http://localhost:12001/swagger-ui.html#/

Refer to this code base for more details: https://github.com/sanketsw/SpringBoot_REST_API

于 2016-03-10T05:01:42.990 回答
0

我意识到这来晚了，但这里有一个可供您考虑的替代方案：您可以手写 OpenAPI API 描述，而不是从您的实现中生成 OpenAPI API 描述，然后让您的实现在启动时读取它并自动配置它的 URL 路由、响应类型等。

即从文档生成实现，而不是从实现生成文档。

我不知道这在春天有多可行（对不起）。使用 Python 和 WSGI 并不难。

这是否是一个好主意只是你可以做出的判断。

于 2018-02-03T03:51:40.783 回答