springBoot 整合 swagger2 构建RESTful API文档

springBoot 整合 swagger2 构建RESTful API文档

1， 添加Swagger2依赖

<!-- 添加Swagger2依赖 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.4.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.4.0</version>
        </dependency>

2，创建Swagger2配置类

在spring boot启动类所在包或子包中创建Swagger配置类SwaggerConfig.java，如下
apis(RequestHandlerSelectors.basePackage(“com.baosight”))// 指定扫描包下面的注解，可以扫描到指定包下面的所有注解，然后将扫描到的@Controller都纳入到这个api的管理界面

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.baosight"))// 指定扫描包下面的注解
                .paths(PathSelectors.any())
                .build();
    }
    // 创建api的基本信息
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("集成Swagger2构建RESTful APIs")
                .description("集成Swagger2构建RESTful APIs")
                .termsOfServiceUrl("https://www.baidu.com")
                .contact("工学院")
                .version("1.0.0")
                .build();
    }


}

@Configuration是spring的注解，表明这是一个配置类，没啥好说的。
@EnableSwagger2自然是Swagger2的注解，源码如下，使用@Import导入Swagger2DocumentationConfiguration配置类，有兴趣可以看看这个类的源码，就能明白原理了

@Retention(RetentionPolicy.RUNTIME)
@Target({java.lang.annotation.ElementType.TYPE})
@Documented
@Import({Swagger2DocumentationConfiguration.class})
public @interface EnableSwagger2 {}

3，创建Controller: SwaggerController.java

@Api这个注解作用就是说明这个api的作用

@RestController
@RequestMapping(value="/swagger")
@Api("swaggerDemoController相关的api")
public class SwaggerController {

    @Autowired
    private TSUserService tSUserService;

    @Autowired
    private QywxMenuService qywxMenuService;

    @ApiOperation(value="获取用户信息", notes="根据id来获取用户详细信息")
    @ApiImplicitParam(name = "id", value = "ID", paramType = "path", required = true, dataType = "String")
    @RequestMapping(value = "/{id}", method = RequestMethod.GET)
    public List getInfo(@PathVariable String id) {
        Assist assist = new Assist();
        //根据id查询
        assist.setRequires(Assist.andEq("qywx_menu.id", id));
        assist.setStartRow(1);
        assist.setRowSize(10);
        return qywxMenuService.selectQywxMenu(assist);
        //return tSUserService.selectTSUser(assist);
    }
}

4，启动Spring boot，访问Swagger UI界面：http://localhost:8081/swagger-ui.html

可以看到有两个contorller，是因为我扫描的包下面有两个

展开swaggerDemoController，就可以输入参数id的值，点击try it out，就可以看到请求路径（Request url）和返回数据（Response body）

这样一个api就完成了