springboot集成swagger

Swagger

• swagger是一个完整的api文档框架，适合团队和个人的强大而易于使用的API开发工具套件的，它涉及到了API开发生命周期从设计和文档、测试和部署
• 通过注解自动生成在线文档
• 接口在线调用调试

集成springboot

1. jar包引入（gradle）

   compile group: 'io.springfox', name: 'springfox-swagger2', version: '2.8.0'
   compile group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.8.0'
   // Swagger-Bootstrap-UI
   compile group: 'com.github.xiaoymin', name: 'swagger-bootstrap-ui', version: '1.7.9'

   注：github上看到了xiaoymin的Swagger-Bootstrap-UI项目，感觉页面比Swagger官方更适用，可以玩一下

2. Swagger配置编写

   @Configuration
   @EnableSwagger2
   public class SwaggerConfig {
   @Value("${base.package:com.zml}")
   public String rootPackage;
   
   @Bean
   public Docket productApi() {
      return new Docket(DocumentationType.SWAGGER_2)
              .select()
              .apis(RequestHandlerSelectors.basePackage(rootPackage))
              .build()
              .apiInfo(metaData());
   }
   
   private ApiInfo metaData() {
      ApiInfo apiInfo = new ApiInfo(
              "Swagger Test API",
              "Swagger Test API",
              "1.0",
              "Terms of service",
              new Contact("zhangml", "https://github.com/zhang-minglei", "test@163.com"),
              "Apache License Version 2.0",
              "https://www.apache.org/licenses/LICENSE-2.0",
              Arrays.asList(new StringVendorExtension[]{new StringVendorExtension("zml", "zml")})
      );
      return apiInfo;
   }
   }

为类、方法、属性添加注解

Swagger常用注解

• @Api：用于controller类上，说明该类的作用
• @ApiOperation：用在controller的方法上，方法说明
• @ApiModelProperty：用在出入参数对象的字段上，说明字段含义
• @ApiResponses：用在controller的方法上，用于表示一组响应
• @ApiResponse：用在 @ApiResponses里边
• @ApiImplicitParam：用来给方法入参增加说明
• @ApiImplicitParams：用在controller的方法上，一组@ApiImplicitParam
• @ApiModel：用在返回对象类上，描述一个Model的信息

注解使用示例

@ApiModel(description = "Swagger测试实体类")
public class SwaggerModel {
    @ApiModelProperty(value = "名称", example = "zml")
    private String name;
}

@Api(tags = "Swagger测试controller类", description = "Swagger测试controller类")
public class SwaggerController {

    @Autowired
    SwaggerService swaggerService;

    @ApiOperation(value = "test", notes = "method test", response = Response.class)
    @ApiImplicitParams(
            {@ApiImplicitParam(name = "id", value = "ID", defaultValue = "1", required = true, dataType = "long", paramType = "path"), 
                    @ApiImplicitParam(name = "name", value = "name", defaultValue = "zml", required = true, dataType = "String", paramType = "path")})
    @RequestMapping(value = "/in/{id}/{name}/{language}", method = RequestMethod.POST)
    public Response testSwagger(@PathVariable("id") long id, @PathVariable("name") String name) {
        return null;
    }
}

页面展示

使用Swagger-UI的页面

页面地址：http://127.0.0.1:10010/swagger-ui.html

使用Swagger-BootStrap-UI的页面
页面地址：http://127.0.0.1:10010/doc.html

集成遇到的坑

• 如果没有编写Swagger配置类，会出现这样的错误：

  打开swagger页面时提示：Unable to infer base url. This is common when using dynamic servlet registration or when the API is behind an API Gateway. The base url is the root of where all the swagger resources are served. For e.g. if the api is available at http://example.org/api/v2/api-docs then the base url is http://example.org/api/. Please enter the location manually: