swagger 自动生成Api文档

本文针对spring boot 1.4 进行集成

maven安装

加入spring fox、swagger包、spring fox swagger ui包

        <springfox-version>2.6.1</springfox-version>
        <swagger-core-version>1.5.10</swagger-core-version>

        <!-- Api文档 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${springfox-version}</version>
        </dependency>
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-core</artifactId>
            <version>${swagger-core-version}</version>
        </dependency>

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${springfox-version}</version>
        </dependency>

spring boot 配置

• 在Application类中增加@EnableSwagger2

@ComponentScan({ "com.qiya.*" })
@SpringBootApplication
@EnableJms
@EnableSwagger2
public class ApiApplication {
    public static void main(String[] args) {
        SpringApplication.run(ApiApplication.class, args);
    }

• 增加一个config类型新类，针对swagger配置说明，以及针配置相关全局参数、以及配置对应的文档分组。

  • 增加Api说明

  private ApiInfo bizApiInfo() {
          return new ApiInfoBuilder()
                  .title("闪信Api")   
                  .contact(new Contact("奇伢", "http://www.qiya.tech", "[email protected]"))
                  .version("1.0.0")
                  .build();
  

• 增加相应需要中上Api说明的controller地址,可以用正则匹配

private Predicate<String> bizPaths() {
        return or(
                regex("/getLeftMessageCount.*"),
                regex("/getBuyLeftCount.*"),
                regex("/getMessageOrder.*"),
                regex("/sendMsgV1.*"),
                regex("/sendMessageAgain.*"),
                regex("/createOrderBefore.*"),
                regex("/createOrder.*"),
                regex("/updateOrderStatus.*"),
                regex("/updateOrderFail.*"),
                regex("/orderDealSuccess.*"),
                regex("/sendMessage.*"),
                regex("/addMsgStatus.*"),
                regex("/pushIOSMsg.*"),
                regex("/getSmsStatus.*"),
                regex("/getMessageHistory.*")
            );
    }

• 把之前两步合并生成文档类，
  • 如果要增加全局参数，如果token，可以在这块增加。
  • 如果有一些实体类嵌套比较深，也可以这里增加实体的引用

@Bean
    public Docket springfoxBiz() {
        ArrayList<Parameter> arrayList = new ArrayList();
        arrayList.add((new ParameterBuilder()
                .name(tokenName)
                .description("存储用户信息的token,仅在需要登录操作中使用")
                .modelRef(new ModelRef("string"))
                .parameterType("header")
                .required(false)
                .build()));

         return (new Docket(DocumentationType.SWAGGER_2)
                .groupName("flashApi")
                .useDefaultResponseMessages(false)
                .apiInfo(bizApiInfo())
                .select()
                .paths(bizPaths())
                .build())
                .additionalModels(typeResolver.resolve(User.class))
                .globalOperationParameters(arrayList);
    }

业务controller代码 配置

• 在方法头加上注释，并分好目录

@ApiOperation(value = "终端返馈短息处理情况",tags = {"闪信"} )

• 增加请求参数json参数的格式（因为springfox版本问题，解析不了swwaggerw例子，所以作备注处理）

@ApiParam(value = "{\"id\":\"1234\",\"status\":\" 0 or 1\",\"deviceType\":\"enterprise or app\"}", required = true)
            @RequestBody String json

运行效果展示

运行地址：http://localhost:9029/swagger-ui.html

生产系统部署

未完待续

最佳实践

1. 定义controller最好按业分级如 /业务/模块功能/方法 /通用/模块功能/方法