Spring Boot集成SwaggerAPI文档

接上次博客发布之后就在想模板工具上还有什么可以添加东西，后面翻了一下以前写的博客发现在spring boot的章节里没有说过swagger的应用。故写这篇博客进行记录

1.Swagger

swagger的出现可以说是必然，它的出现大大在减少了API DOC生成的困难，要知道大的系统的API可能数以万计。通过侵入式的注解埋点，我们在启动服务后能直接生成出该服务对应的REST API文档

1.1 机制

通过开发人员在开发过程中，事先对类和api接口添加对应注解，在启动中通过拦截注解生成前端看到API文档

1.2 基本注解

@Api

使用在api类上，说明该类的分类

@ApiOperation

使用在api类上的方法上标注具体RestAPI的名字，作用还有METHOD

@ApiModel

使用在POJO中，命名POJO

@ApiModelProperty

描绘POJO字段

1.3 效果

2.编写代码

2.1 配置启用注解

pom.xml

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

配置文件需要添加@EnableSwagger2，这里要注意的是basePackage必须包含注解类在内，且配置文件必须处于basePackage之上
SwaggerConfig

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("org.example"))
                .paths(PathSelectors.any())
                .build();
    }


    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("测试 APIs")
                .description("测试api接口文档")
                .version("1.0")
                .build();
    }
}

2.2 注解

Controller

@RestController
@RequestMapping("/servercost")
@Api(tags = "ServerCost对象")
public class ServerCostController {
@Autowired
private ServerCostService ServerCostService;


    @RequestMapping(value = "list", method = RequestMethod.GET)
    @ApiOperation(value = "查询",notes = "列表查询")
    public List<ServerCostVO> list()
    {
        return ServerCostService.list();
    }


    @RequestMapping(value = "insert", method = RequestMethod.POST)
    @ApiOperation(value = "新增",notes = "新增")
    public void insert(@RequestBody ServerCostVO vo)
    {
        ServerCostService.insert(vo);
    }



    @RequestMapping(value = "update", method = RequestMethod.PUT)
    @ApiOperation(value = "更新",notes = "更新")
    public void update(@RequestBody ServerCostVO vo)
    {
        ServerCostService.update(vo);
    }


    @RequestMapping(value = "get/{id}", method = RequestMethod.GET)
    @ApiOperation(value = "查询",notes = "查询单个")
    public ServerCostVO get(@PathVariable("id") String id)
    {
        return ServerCostService.get(id);
    }

    @RequestMapping(value = "delete/{id}", method = RequestMethod.DELETE)
    @ApiOperation(value = "删除",notes = "删除")
    public void delete(@PathVariable("id") String id)
    {
        ServerCostService.delete(id);
    }
}

POJO

@ApiModel("ServerCost对象")
public class ServerCostPO implements Serializable
{
    @ApiModelProperty("cost名称")
    @NotNull(message="cost名称不能为空")
    private String costName;
    @ApiModelProperty("cost值")
    
    private BigDecimal costValue;
    @ApiModelProperty("最后一次更新")
    @NotNull(message="最后一次更新不能为空")
    private Date lastUpdate;
    @ApiModelProperty("commet")
    
    private String comment;
    @ApiModelProperty("默认值")
    
    private BigDecimal defaultValue;
}

2.3 最终效果

3.番外 swagger-bootstrap-ui

在后面的工作中发现了原始的swagger虽然已经自带生成了webui,但是在几年使用下来后发现美式的排版不太适合我们的团队，于是乎在后面的挖掘中，找到了一个国内的开源ui，swagger-bootstrap-ui。

使用无需做任何操作，只需要引入

        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.6</version>
        </dependency>

访问http://ip:port/doc.html

swagger-bootstrap-ui: https://github.com/xiaoymin/swagger-bootstrap-ui

后续版本knife4j：https://gitee.com/xiaoym/knife4j

本次博客github:   https://github.com/tale2009/springboot/tree/master/springboot-swagger