swagger暴露程序接口文档

Swagger2是一个帮助用户、团队、企业快速、高效、准确地生产API服务的工具组件，同时还提供了部分测试功能，它的官方网站是https://swagger.io/。

1.引入Maven

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

2.在应用启动类上添加注解@EnableSwagger2用以开启Swagger2

@SpringBootApplication
@EnableSwagger2
public class DemoApplication {

    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }

}

实际上在执行完上面两个步骤后，接口就已经被暴露出来了，这时我们启动应用，进入网站http://ip:port/swagger-ui.html，可以看到如下界面

上图中已经暴露出来了四个不同的处理器，但是其中只有“user-controller”是由我们创建的，同时这些处理器和页面中没有任何的相关提示，让人难以理解每个接口分别对应的功能。下面我们再进行第三步，对暴露出来的接口再进行详细地描述。

3.添加API文档描述

定义文档的整体描述，和API文档的规范

@Configuration
public class SwaggerConf {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())  //Api信息
                .select()  //选择器
                .apis(RequestHandlerSelectors.basePackage("com.springboot.demo.controller"))  //只有在这个包和子包下的接口被生成API文档
                .paths(PathSelectors.any())  //允许的路径,可以指定post
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("swagger2 demo")  //文档标题
                .description("swagger2的测试用例")  //文档说明
                .contact(new Contact("yxf", "http://yxf.com", "5@qq.com"))  //文档提供者的联系方式
                .version("1.0")  //版本号
                .build();
    }

}

再根据每个接口定义各自的相关描述

    /**
     *  1.@ApiOperation 描述Api的操作，包括请求名(value)和请求描述(notes)
     *  2.@ApiImplicitParams 多个请求参数，里面以数组形式存储了单个的请求参数
     *  3.@ApiImplicitParam 单个请求参数，name参数名，value参数描述，required必要性(针对部分参数可以为空的情况)，
     *          example样例格式(默认是“String”，0，true等)
     * @param id
     * @return
     */
    @ApiOperation(value = "删除角色", notes = "根据ID删除角色。")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "角色ID", required = true, example = "1")
    })
    @DeleteMapping(value = "role/")
    public String removeRole(long id) {
        System.out.println("删除角色");
        return "删除成功" + id;
    }

如上编写后，重启应用再进入上面的方法路径“/role/”查看：

点击“try it out”

执行后下方会出现操作的相关信息：