参考自蚂蚁课堂

链接：http://www.mayikt.com/

概述

随着微服务架构体系的发展和应用，为了前后端能够更好的集成与对接，同时为了项目的方便交付，每个项目都需要提供相应的API文档。

传统的API文档编写存在以下几个痛点:

1.对API文档进行更新的时候，需要通知前端开发人员,导致文档更新交流不及时;API接口返回信息不明确缺乏在线接口测试，通常需要使用相应的API测试工具，比如postman、SoapUl等
2.接口文档太多，不便于管理
3.为了解决传统API接口文档维护的问题，为了方便进行测试后台Restful接口并实现动态的更新，因而引入Swagger接口工具。

Swagger具有以下优点：

1.功能丰富:支持多种注解，自动生成接口文档界面，支持在界面测试API接口
功能;
2.及时更新:开发过程中花- -点写注释的时间，就可以及时的更新API文档，省
心省力;
3.整合简单:通过添加pom依赖和简单配置，内嵌于应用中就可同时发布API
接口文档界面，不需要部署独立服务。

pom引入依赖

        <!--  接口文档  -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>3.0.0</version>
        </dependency>

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

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-common</artifactId>
            <version>3.0.0</version>
        </dependency>

新建配置文件 SwaggerConfig


/**
 * @author 索悻流年
 * @title:接口文档配置类
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    //        RequestHandlerSelectors.any() 扫描所有
    //        RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class) 扫描带有ApiOperation注解
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any()).build();
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("会员服务")
                .description("个人练习项目")
                .version("1.0")
                .build();
    }
}

新建Server

@RestController
@RequestMapping("/user")
@Api(tags = "用户接口")
public class UserController {

    @ApiOperation("接口详细描述")
//    接口参数描述
    @ApiImplicitParam(name = "id", value = "用户id", required=true, dataType = "String")
//    生成post请求接口
    @PostMapping("/swaggerIndex")
    public String swaggerIndex(String id){
        return "测试swagger";
    }


    /**
     * 手机号登录
     * @param phoneNumber 手机号
     * @param passwork 密码
     * @return
     */
    @ApiOperation("手机号登录")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "phoneNumber",value = "手机号",required = true),
            @ApiImplicitParam(name = "passwork",value = "MD5 加密后的密码",required = true),
    })
    @PostMapping("/login")
    BaseResponse<UserDto> login(Spring phoneNumber,String passwork);

}