Swagger——最接近实际开发的接口文档工具

一、Swagger对于实际开发过程中有什么用？

面向WEB应用的开发一定离不开前端和后端两个话题。一个优秀的，成熟的开发团队，无论是从学生时代的组队课程成设计，还是从公司里择选的程序员组成的开发团队，一定离不开分工明确，协同开发。在经过了需求分析后，后端根据业务逻辑实现相应的接口，前端自己模拟数据实现页面布局。Swagger在这其中充当前后端联系的胶水【接口文档】，后端在测试运行项目的时候，无需刻意编写对应接口的一些解释说明，参数、返回值说明，可以通过这个工具在线生成对应的模块以及对应接口说明，前端只需要通过浏览器访问就了解到方法的使用，发起请求需要哪些参数，或者接受数据时怎么使用。
Swagger官网： https://swagger.io/

二、Swagger效果图

访问连接是：http://ip地址:端口号/swagger-ui.html。
这里我是本地运行后端springBoot，所以访问url：http://localhost:8088/swagger-ui.html

对应模块视图：
用户模块的接口：

接口的参数以及返回情况：

三、如何配置使用swagger？

  ## 引入依赖pom.xml

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

当然也可以自己去maven中下载自己想要的版本。https://mvnrepository.com/

编写配置文件，并开启相应服务

@Configuration
//@Configuration修饰的AppConfig是一个cglib的代理对象
// 所以@Configuration 保证了配置类的内部方法之间依赖调用时都从容器中获取bean
@EnableSwagger2
//开启swagger2
@EnableKnife4j
//开启knife4j(swagger+)
public class Swagger2Config {

    @Bean
    public Docket createRestApi() {
        return  new Docket(DocumentationType.SWAGGER_2)
                .useDefaultResponseMessages(false)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.missbear.gradution.design.controller"))//扫描接口包
                .paths(PathSelectors.any())//进一步完善接口扫描
                .build();

    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .contact(new Contact("负责人姓名","博客地址","邮箱联系"))//api 负责人联系信息
                .title("基于云平台的开放式物联网创新实验教学系统")//swagger api页面的标题
                .description("后端接口文档")//swagger api页面的描述
                .termsOfServiceUrl("http://localhost:8088/")//服务地址
                .version("1.0")//开发版本号
                .build();
    }
    }

相关Api接口配置和说明作用如下:

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

四、注意，如果人为swagger界面不够友善，可以尝试swagger的升级版。

修改依赖导入：

        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <!--在引用时请在maven中央仓库搜索最新版本号-->
            <version>3.0.3</version>
        </dependency>

对应访问地址也发生变化：http://localhost:8088/doc.html

1. 参考一：springBoot集成swagger2
2. 参考二：Swagger2常用注解说明
   代码参考：交通大学 物联网学长——朱学长