springBoot集成swagger2

1 背景

springBoot作为微服务首选框架,为其他服务提供大量的接口服务。接口对接方需要实时最近的接口文档。

swagger可以通过代码和注释自动为web项目生成在线文档,这里使用swagger。

swagger官网地址:https://swagger.io/

2 使用

2.1 maven依赖

    
    io.springfox
    springfox-swagger2
    2.9.2


    io.springfox
    springfox-swagger-ui
    2.9.2

依赖说明:

(1)springfox-swagger2

检测spring的web请求信息,生成检测结果(json格式)。

(2)springfox-swagger-ui

根据springfox-swagger2生成的数据,生成可视化的友好页面。

2.2 配置代码

Springfox提供Docket对象,为其设置相关属性,将其注册成为spring的bean后,可以在接口文档中展示(可配置多个Docket的bean,对应不同分组的接口)

@Configuration
@EnableSwagger2
public class Swagger2Conf {
    @Bean
    public Docket getUserDocket(){
        ApiInfo apiInfo=new ApiInfoBuilder()
                .title("用户管理")//api标题
                .description("用户管理相关接口描述")//api描述
                .version("1.0.0")//版本号
                .contact("sabre")//本API负责人的联系信息
                .build();
        return new Docket(DocumentationType.SWAGGER_2)//文档类型(swagger2)
                .apiInfo(apiInfo)//设置包含在json ResourceListing响应中的api元信息
                .select()//启动用于api选择的构建器
                .apis(RequestHandlerSelectors.basePackage("com.scaf.test.web.boot.controller.api"))//扫描接口的包
                .paths(PathSelectors.any())//路径过滤器(扫描所有路径)
                .build();
    }
}

其中@Configuration、@Bean均为spring初始化bean相关的注解。@EnableSwagger2表示启用swagger2。

2.3 接口配置

通过在控制器和接口方法上加上相关注解,可以给接口和控制器添加相关的接口说明信息。

常用注解如下:

注解 使用的地方 用途
@Api 类/接口 描述类/接口主要用途
@ApiOperation 方法 描述方法的用途
@ApiImplicitParam 方法 用于描述接口的非对象参数
@ApiImplicitParams 方法 用于描述接口的非对象参数集
@ApiIgnore 类/方法/参数 Swagger 文档不会显示拥有该注解的接口
@ApiModel 参数实体类 可设置接口相关实体的描述
ApiModelProperty 参数实体类属性 可设置实体属性的相关描述

参数实体类代码:

@ApiModel("用户")
public class UserInfo {
    
    @ApiModelProperty("用户ID")
    private Integer id;
    
    @ApiModelProperty("用户代码")
    private String userCode;
    
    @ApiModelProperty("用户姓名")
    private String userName;
    
    @ApiModelProperty("年龄")
    private Integer age;
}

接口代码:

@Api("用户管理api")
@RestController
@RequestMapping("/userApi")
public class UserApiController {
    
    @Autowired
    private UserApiService userApiService;
    
    @ApiOperation("查询用户信息")
    @PostMapping("/findUserList")
    public JSONObject findUserList(){
        JSONObject jsonObject=new JSONObject();
        jsonObject.put("success",true);
        jsonObject.put("result",userApiService.findUserList());
        return jsonObject;
    }
    
    @ApiOperation("保存用户")
    @PostMapping("saveUser")
    public JSONObject saveUser(@RequestBody UserInfo userInfo){
        userApiService.saveUser(userInfo);
        JSONObject jsonObject=new JSONObject();
        jsonObject.put("success",true);
        jsonObject.put("message",null);
        return jsonObject;
    }
}

2.4 访问

启动项目后,通过以下方式访问swagger2的接口说明

http://地址:端口/应用名/swagger-ui.html

如:http://localhost:8080/swagger-ui.html

3 其他

3.1 访问swagger2接口源信息

通过如下方式访问:

http://地址:端口/应用名/v2/api-docs

如:http://localhost:8080/v2/api-docs

返回的json格式如下:

{"swagger":"2.0","info":{"description":"用户管理相关接口描述","title":"用户管理"},"host":"localhost:8080","basePath":"/","tags":[{"name":"user-api-controller","description":"User Api Controller"}],"paths":{"/userApi/findUserList":{"post":{"tags":["user-api-controller"],"summary":"findUserList","operationId":"findUserListUsingPOST","consumes":["application/json"],"produces":["*/*"],"parameters":[{"in":"body","name":"userInfo","description":"userInfo","required":true,"schema":{"$ref":"#/definitions/UserInfo"}}],"responses":{"200":{"description":"OK","schema":{"type":"object","additionalProperties":{"type":"object"}}},"201":{"description":"Created"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}},"deprecated":false}},"/userApi/saveUser":{"post":{"tags":["user-api-controller"],"summary":"saveUser","operationId":"saveUserUsingPOST","consumes":["application/json"],"produces":["*/*"],"parameters":[{"in":"body","name":"userInfo","description":"userInfo","required":true,"schema":{"$ref":"#/definitions/UserInfo"}}],"responses":{"200":{"description":"OK","schema":{"type":"object","additionalProperties":{"type":"object"}}},"201":{"description":"Created"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}},"deprecated":false}}},"definitions":{"UserInfo":{"type":"object","properties":{"age":{"type":"integer","format":"int32"},"id":{"type":"integer","format":"int32"},"userCode":{"type":"string"},"userName":{"type":"string"}},"title":"UserInfo"}}}

swagger-ui通过对此源信息的解析,生成相关页面

3.2 swagger2静态资源

swagger通过webjars的方式,来实现网页方式的接口访问。

如配置拦截器、shiro、spring security等,需对以下页面放行,来保证swagger页面的正常访问:

/swagger*/**
/v2/**
/webjars/**

如下,spring拦截器,需配置如下:




你可能感兴趣的:(springBoot集成swagger2)