swagger+springmvc接口在线文档完美整合

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务。Swagger是世界上最大的API开发框架，它能使后端的接口形成API文档。使用Swagger可以让前后端开发更高效，使代码解耦，减少前后端开发人员之间沟通鸿沟，让前后端开发人员更友好协调开发。

先给一张效果图（使用swagger整合生成的API接口文档）

项目中需要依赖的swagger包

 <!--swagger begin-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.2.2</version>
        </dependency>
<!--swagger-bootstrap-ui-->
        <dependency>
            <groupId>com.drore.cloud</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.4</version>
        </dependency>

Swagger-Bootstrap-UI是Swagger的前端UI实现,采用jQuery+bootstrap实现,目的是替换Swagger默认的UI实现Swagger-UI,使文档更友好一点儿

（Swagger-Bootstrap-UI 官网：https://git.oschina.net/xiaoym/swagger-bootstrap-ui）

项目Controller层

@RestController
@RequestMapping(value = "/user", produces = {"application/json;charset=utf-8"})
@Api(value = "用户中心", description="用户中心")
public class UserController {

    @Autowired(required = false)
    private UserService userService;

    @Autowired
    private DemoService demoService;

    @RequestMapping(value = "/addUser", method = RequestMethod.POST)
    @ApiOperation(notes = "新增用户", httpMethod = "POST", value = "添加一个用户")
    @ApiResponses(value = {@ApiResponse(code = 405, message = "invalid input")})
    @ResponseBody
    public boolean addUser(@ApiParam(required = true, value = "group data") @RequestBody User user) {
        return userService.insert(user);

    }

    @RequestMapping(value = "/updateUser", method = RequestMethod.POST)
    @ApiOperation(notes = "更新用户", httpMethod = "POST", value = "更新一个用户")
    @ApiResponses(value = {@ApiResponse(code = 405, message = "invalid input")})
    @ResponseBody
    public boolean updateUser(@ApiParam(required = true, value = "用户信息") @RequestBody User user) {
        return userService.updateById(user);
    }

    @RequestMapping(value = "/getUser", method = RequestMethod.POST)
    @ApiOperation(notes = "获取用户", httpMethod = "POST", value = "获取一个用户")
    @ApiResponses(value = {@ApiResponse(code = 405, message = "invalid input")})
    @ResponseBody
    public User updateUser(@ApiParam(required = true, value = "用户信息") @RequestBody Integer id) {
        return userService.selectById(id);
    }

实体类

@ApiModel(description = "用户中心")
@TableName("user")
public class User {
    /**
     * 用户标识
     */
    @ApiModelProperty(required = true, value = "用户标识")
    private Long id;
    /**
     * 用户名
     */
    @ApiModelProperty(required = true, value = "用户名")
    private String username;
    /**
     * 密码
     */
    @ApiModelProperty(required = true, value = "密码")
    private String passwords;
    /**
     * 邮箱
     */
    @ApiModelProperty(required = true, value = "邮箱")
    private String email;
    /**
     * 电话
     */
    @ApiModelProperty(required = true, value = "电话")
    private String telephone;
    /**
     * 地址
     */
    @ApiModelProperty(required = true, value = "地址")
    private String address;

    public long getId() {
        return id;
    }

    public void setId(long id) {
        this.id = id;
    }

    public String getUsername() {
        return username;
    }

    public void setUsername(String username) {
        this.username = username;
    }

    public String getPasswords() {
        return passwords;
    }

    public void setPasswords(String passwords) {
        this.passwords = passwords;
    }

    public String getEmail() {
        return email;
    }

    public void setEmail(String email) {
        this.email = email;
    }

    public String getTelephone() {
        return telephone;
    }

    public void setTelephone(String telephone) {
        this.telephone = telephone;
    }

    public String getAddress() {
        return address;
    }

    public void setAddress(String address) {
        this.address = address;
    }


}

Swagger初始化配置

@Configuration
@EnableSwagger2
public class ApplicationSwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("trade.axht"))
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        ApiInfo apiInfo = new ApiInfoBuilder()
                .title("后台在线接口文档")
                .description("swagger-bootstrap-ui")
                .termsOfServiceUrl("http://localhost:8080/")
                .contact("[email protected]")
                .version("1.0")
                .build();
        return apiInfo;
    }
}

spring-mvc.xml配置（需要运行静态资源直接访问，不用拦截）

<!-- Enables swgger ui-->
    <mvc:resources mapping="/webjars/**" location="/webjars/"/>
    <mvc:resources mapping="/doc.html" location="/doc.html"/>
    <mvc:resources mapping="/v2/api-docs" location="/v2/api-docs"/>

    <!-- Scan some API controllers-->
  <!--  <context:component-scan base-package="springfox.petstore.controller"/>-->
    <context:component-scan base-package="trade.axht.controller"/>
    <!-- Include a swagger configuration-->
    <bean name="applicationSwaggerConfig" class="trade.axht.swagger.ApplicationSwaggerConfig"/>

其他配置跟springmvc配置差不多。swagger-bootstrap-ui包里面有静态资源，里面包含swagger所需要的所有样式，所有开发人员不必新增样式，直接引用即可。