Question

我一直在考虑招摇，以便为我的团队的api http://swagger.io/getting-started/自动生成文档。这似乎很有希望，但我发现他们的文档缺乏。

话虽如此，我有一些非常基本的问题。

只使用Spring应用程序可以使用swagger吗？我们的应用程序既不是运动衫也不是JAX-RS应用程序。有谁知道一个简单的Spring应用程序是否可以与swagger一起使用？如果是这样，可以提供一个或一组指令吗？

我找到了这个链接http://blog.zenika.com/index.php?post/2013/07/11/Documenting-a-REST-API-with-Swagger-and-Spring-MVC，但他们略过了关于设置属性文件的内容。

swagger在他们的网站上引用了许多不同的工具swagger core，codegen，ui和swagger编辑器。是否只需要swagger-core来生成他们的基本API文档，或者是否需要组合swagger工具？

Answer 1

有一页专门用于support swagger frameworks。

您要找的是SpringFox。

使用Spring构建的API的自动JSON API文档

基本上，您使用指向API上下文的Docket对象来应用配置。您需要花时间，因为有一些配置可以使其工作，而不是根据您的应用需求进行扩展。

 @Bean
    public Docket documentation() {
        return new Docket()
          .select()
            .apis(RequestHandlerSelectors.any())
            .paths(regex("/api/.*"))
            .build()
          .pathMapping("/")
          .apiInfo(metadata());
    }

您可能已经知道，您可以在许多其他功能中添加注释，例如可能的HTTP响应代码等。确实很有希望。

@ApiOperation(value = "doStuff", nickname = "doStuff", response = DoStuffResult.class)
@Responses({
    @ApiResponse(code =  404, message ="Not found", response = GenericError.class),
    @ApiResponse(code =  400, message ="Invalid input", response = GenericError.class)
})
@RequestMapping(method = RequestMethod.GET, produces = "application/json")
public ResponseEntity<?> doStuff(@RequestBody DoStuffCommand command) {
    // Stuff
}

以下是我在网上找到的best example，非常简短而客观。

Answer 2

对于我的工作：

在pom中添加了以下依赖项：

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

然后将@ EnableSwagger2添加到spring配置文件和swagger UI所需的注册资源处理程序，如：

@Configuration
public class YourConfigFileHere extends WebMvcConfigurerAdapter {


    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/resources/**").addResourceLocations(
            "/resources/");

        registry.addResourceHandler("swagger-ui.html").addResourceLocations(
            "classpath:/META-INF/resources/");

        registry.addResourceHandler("/webjars/**").addResourceLocations(
            "classpath:/META-INF/resources/webjars/");
    }

    // rest of the configuration
}

这将使基本的swagger UI启动并运行。如果要自定义，可以通过添加使用@ EnableSwagger2注释的swagger配置文件并使用@Import将其导入spring配置文件来实现。

对于本地环境，您可以访问swagger-ui：

http://localhost:8080/{context-root}/swagger-ui.html

Answer 3

如上所述，springfox是spring-mvc的一流招摇图书馆。您还可以使用swagger-samples存储库中演示的弹簧配置。

您可以通过访问http://editor.swagger.io并创建一个swagger定义来查看此工作示例。从那里，您可以下载一个支持swagger的spring-mvc服务器。

Java Spring应用程序可以利用swagger

3 个答案: