5分钟搞定Swagger2环境配置与使用

Maven配置

在pom.xml中加入依赖

  io.springfox
  springfox-swagger2
  2.7.0


  io.springfox
  springfox-swagger-ui
  2.7.0

与SpringMvc集成

增加JavaConfig配置文件

@Configuration
@EnableWebMvc
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket buildDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(buildApiInf())
        .host("localhost:8080")
        .select()
        .apis(RequestHandlerSelectors.basePackage("com.dianping.orderdish.webapi"))//controller路径
        .paths(PathSelectors.any()).build();
    }

    private ApiInfo buildApiInf() {
        return new ApiInfoBuilder()
        .title("RestAPI Docs")
        .termsOfServiceUrl("http://www.github.com/kongchen/swagger-maven-plugin")
        .build();

    }
}

如果Spring MVC代理了根路径（\)的url，在spring-mvc.xml增加配置项。

启动Tomat，通过localhost:8080/swagger-ui.html访问Swagger-UI。

Maven插件生成API描述文档（json格式）

 com.github.kongchen
 swagger-maven-plugin
 3.1.5
 
     
         
             true
             com.example.demo13
             orderdish-ecom-web.51ping.com
             /s
             http,https
             
                 
                 v1
                 Click Link Below for Help
                 http://www.github.com/kongchen/swagger-maven-plugin
             
             
             
             
             
             ${project.build.directory}/swagger-ui
             yaml,json
         
     
 
 
     
         compile
         
             generate
         
     
 

执行mvn complie，在设置的target目录下会生成API描述文档。

Maven插件生成静态文档（markdown格式）

 io.github.swagger2markup
 swagger2markup-maven-plugin
 1.3.3
 
     
     ${project.build.directory}/swagger-ui/swagger.yaml
     ${project.build.directory}/swagger-ui
     ${project.build.directory}/swagger-ui/swagger.md
     
         
         MARKDOWN
         
         TAGS
     
 
 
     
         compile
         
             convertSwagger2markup
         
     
 

如果mvn complie时出现异常，可能是因为之前生成的yaml不符合Swagger规范。把yaml复制到Swagger Editor中，根据提示的语法错误修正，再手动执行mvn swagger2markup:convertSwagger2markup即可生成markdown文档。

Reference

1. swagger2markup文档