项目swagger-bootstrap-ui对外开放API文档的开发和使用

月影WEB
304 阅读3分钟

持续创作，加速成长！这是我参与「掘金日新计划 · 6 月更文挑战」的第30天，点击查看活动详情

之前的文章有讲过Swagger2对外开放API文档的开发和使用，可能UI没那么好看，这次我们使用swagger-bootstrap-ui这个架包文件；

通过swagger-bootstrap-ui可以让对外开发文档的页面UI更加美观；

下面是效果图：

图0

0-效果图.png

pom.xml文件中加上以下依赖包，加入的代码如下：

    <!--Swagger-->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.9.2</version>
    </dependency>
    <!--swagger-bootstrap-ui-->
    <dependency>
        <groupId>com.github.xiaoymin</groupId>
        <artifactId>swagger-bootstrap-ui</artifactId>
        <version>1.9.6</version>
    </dependency>

如下图：

图1

1.png

然后点击右上角更新架包；

图2

2.png

增加配置文件SwaggerConfig，在类上加上@Configuration和@EnableSwagger2，

@Configuration是为了让项目把此类文件当做配置类文件进行读取；

@EnableSwagger2是为了启动Swagger2；

并增加以下代码：

@Bean
public Docket createRestApi() {
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .groupName("base")
            .select()
            // 要扫描的API(Controller)基础包
            .apis(RequestHandlerSelectors.basePackage("com.yydpt.base"))
            // 要扫描的API(Controller)全局-(就是可以扫描所有的带有api注解的包并生成文档)
            // .apis(RequestHandlerSelectors.any())
            .paths(PathSelectors.any())
            .build();
}

//配置在线文档的基本信息
private ApiInfo apiInfo() {
    Contact contact = new Contact("月影", "http://www.yydpt.com", "363284801@qq.com");
    return new ApiInfoBuilder()
            .title("接口API 文档")
            .description("SpringBoot-Mybatis-Swagger-SwaggerBootstrapUI 对外开放接口API 文档")
            .contact(contact)
            .version("1.0.0")
            .termsOfServiceUrl("http://www.yydpt.com")
            .license("LICENSE")
            .licenseUrl("http://www.yydpt.com")
            .build();
}

如下图所示：

图3

3.png

访问接口是：http://localhost:8080/doc.html

效果图如下：

图4

4.png

然后创建控制器UserController，并加上以下代码：

图5

5.png

图5中代码详解：

@Api

作用: 用来指定接口的描述文字；

修饰范围: 用在类上；

@ApiResponses

作用：用于请求的方法上，表示一组响应；

修饰范围: 用在方法上；

也可以作用在类上，当它作用在类上面的时候，类里面的所有方法均会有对应的响应；

@ApiOperation

作用：用在请求的方法上，说明方法的用途、作用；

修饰范围: 用在方法上；

@ApiImplicitParams：用在请求的方法上，表示一组参数说明
    @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
        name：参数名
        value：参数的汉字说明、解释
        required：参数是否必须传
        paramType：参数放在哪个地方
            · header --> 请求参数的获取：@RequestHeader
            · query --> 请求参数的获取：@RequestParam
            · path（用于restful接口）--> 请求参数的获取：@PathVariable
            · body（不常用）
            · form（不常用）    
        dataType：参数类型，默认String，其它值dataType="Integer"       
        defaultValue：参数的默认值

页面效果如下： 图6、图7、图8、图9

6-页面效果.png

7-页面效果.png

8-页面效果.png

9-页面效果.png

在图9中的username和password的后面输入字段值之后，点击“发送”可以测试该接口的情况；

这样一个JAVA项目的API接口文档就做好了，剩下的就是在每一次写接口的时候加上对应需要的注释即可；

好处就是以后前端再找后端要接口和接口参数的时候，后端直接把这个接口文档发给前端，让他自己去看；

以后也不用再去额外的整理项目中接口的使用情况了，直接就能在此接口文档中看到所有的接口信息了；

关注公众号（月影WEB），了解更多的前后端知识；

欢迎大家关注互相交流学习；

avatar
文章
阅读
粉丝