如何在spring-boot web项目中启用swagger

swagger的三个项目及其作用

我们打开swagger的官网,会发现有三个swagger相关的项目,它们分别是

1. swagger-editor 作用是通过写代码,生成文档描述(一个json文件或其他格式的api元数据文件)
2. swagger-ui 通过请求文档描述(一个json文件)的数据,把api的文档显示在页面上
3. swagger-codegenerator 通过文档描述,来生成实现的代码

如何在spring-boot项目中集成swagger?

我们使用springfox-swagger这个项目来把swagger的功能集成到我们的项目中来,springfox-swagger会自动扫描定义在Controller上的API的相关的注解,生成api的元数据json文件,然后提供的一个swagger的页面,当我们访问这个页面的时候,前端的js会去请求这个API的元数据文件,把API的相关信息展示出来,方便我们阅读和在线调试

集成到spring-boot web项目的步骤:

1.在项目的依赖一遍加入springfox-swagger的相关的依赖

由于我用的构建工具是gradle,所以就用下边的方式来引入依赖,

compile group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.9.2'
compile group: 'io.springfox', name: 'springfox-swagger2', version: '2.9.2'

2.定义swagger的配置类,引入启用swaggger

在spring-boot项目可以自动扫描到的包下边,配置以下的配置类:

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * Created with Intellij IDEA
 *
 * @author: jiaoyiping
 * Mail: jiaoyiping@gmail.com
 * Date: 2018/11/22
 * Time: 15:38
 * To change this template use File | Settings | Editor | File and Code Templates
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket customDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }


    private ApiInfo apiInfo() {
        Contact contact = new Contact("焦一平", "http://www.cnblogs.com/jiaoyiping/", "jiaoyiping@gmail.com");
        return new ApiInfoBuilder()
                .title("元数据管理API接口")
                .description("工具链元数据管理")
                .contact(contact)
                .version("1.1.0")
                .build();
    }
}

3.在Controller里边定义API的相关的注解

以下是一个API注解的例子:

@RequestMapping(value = "/checkprojectcode/{projectcode}", method = RequestMethod.GET)
    @ApiOperation(value = "检查项目编号是否已经存在")
    public ResponseEntity<String> checkProjectCodeExists(@PathVariable("projectcode") String projectCode) {
        ResponseEntity<String> result;
        if (projectService.isProjectCodeExist(projectCode)) {
            result = ResponseEntity.ok("项目编号已存在");
        } else {
            result = ResponseEntity.ok("项目编号不存在");
        }
        return result;
    }

@ApiOperation注解提供了api的名称和描述信息

最终效果

启动项目,访问项目路径下的 v2/api-docs 这个地址,可以看到生成的json数据

访问项目路径下的 swagger-ui.html路径,可以查看和调试我们写的api的信息,所以的被@Controller注解的类都会显示在和这个页面上,添加了额外的api主机的接口,会有额外的描述信息