【spring-boot】使用Swagger2构建RESTful API

通过Swagger2快速构建RESTful API 文档。

演示效果如下：

下面开始贴代码：

1.在pom文件中引入Swagger依赖

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

2.创建Swagger2配置类

package org.spring.springboot.configuration;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.bind.annotation.RequestMethod;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.builders.ResponseMessageBuilder;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.util.Date;
import static com.google.common.collect.Lists.newArrayList;


/**
 *
 * Created by uknowzxt on 27/03/2018.
 */
@Configuration
@EnableSwagger2
public class Swagger2 {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("org.spring.springboot"))//扫描接口的路径包 不要忘记换成自己的路径
                .paths(PathSelectors.any())
                .build()
                .directModelSubstitute(Date.class,String.class)//将date类型全部转化称string
                .useDefaultResponseMessages(false)  //是否启用默认的http码
                .globalResponseMessage(RequestMethod.GET, //配置全局错误码
                        newArrayList(
                                new ResponseMessageBuilder().code(0).message("请求处理成功").build(),
                                new ResponseMessageBuilder().code(1).message("系统错误").build()))
                .globalResponseMessage(RequestMethod.POST,
                        newArrayList(
                                new ResponseMessageBuilder().code(0).message("请求处理成功").build(),
                                new ResponseMessageBuilder().code(1).message("系统错误").build()))
                .globalResponseMessage(RequestMethod.PUT,
                        newArrayList(
                                new ResponseMessageBuilder().code(0).message("请求处理成功").build(),
                                new ResponseMessageBuilder().code(1).message("系统错误").build()))
                .globalResponseMessage(RequestMethod.DELETE,
                        newArrayList(
                                new ResponseMessageBuilder().code(0).message("请求处理成功").build(),
                                new ResponseMessageBuilder().code(1).message("系统错误").build()));
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("使用Swagger2构建RESTful API")
                .description("在记录与总结中进步")
                .termsOfServiceUrl("https://blog.csdn.net/uknowzxt")
                .contact("uknowzxt")
                .version("1.0")
                .build();
    }
}

3.创建文档内容

package org.spring.springboot.controller;

import io.swagger.annotations.*;
import org.spring.springboot.domain.City;
import org.spring.springboot.service.CityService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
import java.util.List;

/**
 * 城市 Controller 实现 Swagger 服务
 *
 * Created by uknowzxt on 27/03/2018.
 */
@Api(description = "城市API" )
@RestController
public class CityRestController {

    @Autowired
    private CityService cityService;

    @ApiOperation("查询一条")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "城市id", paramType = "query", required = true, dataType = "Integer"),
    })@ApiResponses(value = {//方法的返回
            @ApiResponse(code = 200, message = "OK"),
            @ApiResponse(code = 405, message = "城市不存在")
    })
    @RequestMapping(value = "/api/city/{id}", method = RequestMethod.GET)
    public City findOneCity(@PathVariable("id") Long id) {
        return cityService.findCityById(id);
    }

    @ApiOperation("查询列表")
    @ApiImplicitParams({

    })@ApiResponses(value = {//方法的返回
            @ApiResponse(code = 200, message = "OK")
    })
    @RequestMapping(value = "/api/city", method = RequestMethod.GET)
    public List<City> findAllCity() {
        return cityService.findAllCity();
    }

    @ApiOperation("新增")
    @ApiImplicitParams({
    })@ApiResponses(value = {//方法的返回
            @ApiResponse(code = 200, message = "OK")
    })
    @RequestMapping(value = "/api/city", method = RequestMethod.POST)
    public void createCity(@RequestBody City city) {
        cityService.saveCity(city);
    }

    @ApiOperation("修改")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "参数描述", paramType = "query", required = true, dataType = "Integer"),
    })@ApiResponses(value = {//方法的返回
            @ApiResponse(code = 200, message = "OK"),
            @ApiResponse(code = 405, message = "城市不存在")
    })
    @RequestMapping(value = "/api/city", method = RequestMethod.PUT)
    public void modifyCity(@RequestBody City city) {
        cityService.updateCity(city);
    }

    @ApiOperation("删除")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "参数描述", paramType = "query", required = true, dataType = "Integer"),
    })@ApiResponses(value = {//方法的返回
            @ApiResponse(code = 200, message = "OK"),
            @ApiResponse(code = 405, message = "城市不存在")
    })
    @RequestMapping(value = "/api/city/{id}", method = RequestMethod.DELETE)
    public void modifyCity(@PathVariable("id") Long id) {
        cityService.deleteCity(id);
    }
}

4.在实体类上加入注解（不是必要）

package org.spring.springboot.domain;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

/**
 * 城市实体类
 *
 * Created by uknowzxt on 27/03/2018.
 */
@ApiModel("城市")
public class City {

    /**
     * 城市编号
     */
    @ApiModelProperty("城市编号")
    private Long id;

    /**
     * 省份编号
     */
    @ApiModelProperty("省份编号")
    private Long provinceId;

    /**
     * 城市名称
     */
    @ApiModelProperty("城市名称")
    private String cityName;

    /**
     * 描述
     */
    @ApiModelProperty("描述")
    private String description;

    public Long getId() {
        return id;
    }
    ......
}

5.访问

http://localhost:8080/swagger-ui.html

就能看到前文所展示的RESTful API的页面。我们可以再点开具体的API请求，以POST类型的请求为例，可找到上述代码中我们配置的Notes信息以及参数City的描述信息，如下图所示。

如果不对实体类加注解，框中内容是不会有注释的

点击Model右边的Model Schema 出现如下示例，双击此处，左侧Value框中回出现数据，这时点击下方的Try it out！可以直接在API中对接口进行测试。

【spring-boot】使用Swagger2构建RESTful API

猜你喜欢