java 项目 swagger 文档 - 《贺婷学习文档》

首先，我们在 pom.xml 文件里添加一个依赖

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>2.0.7</version>
 </dependency>

然后再建个包，用于防止 swagger 的配置类，如 conf，然后再建一个类，是我们用于配置 swagger 的类。

对以下的代码的备注： initCreateDocket 方法是创建一个接口分组的方法，有时候我们写接口会分为 app 的接口，后台管理的接口等，根据端进行分一下组，不然不同的前端看的是同一套接口就比较乱，我们可以将里面的接口作者等信息稍作修改一下。 createApiAdmin 方法就是创建后台管理的接口，接口前缀是 /xican/admin/ 的就会被划分到这个分组，其他几个方法也是类似的哈。

@Configuration
@EnableSwagger2WebMvc
@Profile(value = {"test", "online", "local", "gs"})
public class SwaggerConf {
    /**
     * 初始化创建 docket
     *
     * @param controllerPathPattern 控制器通配符拦截,表示显示哪些控制器
     * @param groupName             组名
     * @return springfox.documentation.spring.web.plugins.Docket
     * @author chenlijia
     * @since 下午 12:56 2019/8/5 0005
     **/
    private Docket initCreateDocket(String controllerPathPattern, String groupName) {
        ParameterBuilder builder = new ParameterBuilder();
        builder.name(Constants.TOKEN).description("token").modelRef(new ModelRef("string")).parameterType("header").required(false).build();
        ArrayList<Parameter> parameters = Lists.newArrayList();
        parameters.add(builder.build());
        ApiInfo apiInfo = new ApiInfoBuilder().title("喜餐订货管理系统API文档").
                contact(new Contact("陈礼佳", "http://192.168.1.43:8090/toutoumai", "571740367@qq.com")).
                version("1.0").description("喜餐订货管理系统接口").build();
        ApiSelectorBuilder apis = new Docket(DocumentationType.SWAGGER_2).
                apiInfo(apiInfo).select().apis(RequestHandlerSelectors.any());
        if (StringUtils.hasText(controllerPathPattern)) {
            apis.paths(PathSelectors.ant(controllerPathPattern));
        } else {
            apis.paths(PathSelectors.any());
        }
        Docket docket = apis.build();
        if (StringUtils.hasText(groupName)) {
            docket.groupName(groupName);
        }
        //header
        docket.globalOperationParameters(parameters);
        return docket;
    }
    /**
     * 注入swagger配置
     *
     * @return
     */
    @Bean
    public Docket createApiAdmin() {
        Docket docket = initCreateDocket("/xican/admin/**", "后台接口");
        docket.useDefaultResponseMessages(false);
        createResponseMessage(docket);
        return docket;
    }
    /**
     * 注入swagger配置
     *
     * @return
     */
    @Bean
    public Docket createApiSupplierAdmin() {
        Docket docket = initCreateDocket("/xican/supplier/admin/**", "供应商后台接口");
        docket.useDefaultResponseMessages(false);
        createResponseMessage(docket);
        return docket;
    }
    /**
     * 注入swagger配置
     *
     * @return
     */
    @Bean
    public Docket createApiFoodManagerAdmin() {
        Docket docket = initCreateDocket("/xican/food/manager/**", "餐饮后台接口");
        docket.useDefaultResponseMessages(false);
        createResponseMessage(docket);
        return docket;
    }
    /**
     * 注入swagger配置
     *
     * @return
     */
    @Bean
    public Docket createApiSupplierApp() {
        Docket docket = initCreateDocket("/xican/supplier/app/**", "供应商小程序接口");
        docket.useDefaultResponseMessages(false);
        createResponseMessage(docket);
        return docket;
    }
    /**
     * 注入swagger配置
     *
     * @return
     */
    @Bean
    public Docket createApiCanteen() {
        Docket docket = initCreateDocket("/xican/canteen/**", "食堂接口");
        docket.useDefaultResponseMessages(false);
        createResponseMessage(docket);
        return docket;
    }
    /**
     * 注入swagger配置
     *
     * @return
     */
    @Bean
    public Docket createApiSystem() {
        Docket docket = initCreateDocket("/xican/system/**", "系统接口");
        docket.useDefaultResponseMessages(false);
        createResponseMessage(docket);
        return docket;
    }
    /**
     * 注入swagger配置
     *
     * @return
     */
    @Bean
    public Docket createApiRPC() {
        Docket docket = initCreateDocket("/xican/rpc/**", "远程调用接口");
        docket.useDefaultResponseMessages(false);
        createResponseMessage(docket);
        return docket;
    }
    /**
     * 设置返回值状态
     *
     * @param docket 1
     * @return void
     * @author chenlijia
     * @since 下午 12:42 2019/8/5 0005
     **/
    private void createResponseMessage(Docket docket) {
        List<ResponseMessage> list = Lists.newArrayList();
        ResponseStatusEnum[] values = ResponseStatusEnum.values();
        for (ResponseStatusEnum value : values) {
            int code = value.getCode();
            String name = value.getName();
            ResponseMessage responseMessage = new ResponseMessageBuilder().code(code).message(name).build();
            list.add(responseMessage);
        }
        docket.globalResponseMessage(RequestMethod.GET, list);
        docket.globalResponseMessage(RequestMethod.POST, list);
    }

此时，当我们运行项目的时候，访问 http://localhost:端口/ht/doc.html 就可以看到文档了，但是这些方法都没有备注信息。
然后我们找到一个路由，进行配置路由的信息，如下：
类上的 @Api 就是用来标注这个路由分组的名字，@ApiOperation 就是用来这个路由的名字。

@RestController
@RequestMapping(value = "admin/admin")
@Api(tags = "后台用户")
@PropertyCheck
public class AdminController {
    @Autowired
    private AdminBiz biz;
    /**
     * 添加
     *
     * @param params
     * @return
     */
    @PostMapping(value = "add")
    @ApiOperation(value = "添加")
    public Result add(@RequestBody AddParams params) {
        return biz.add(params);
    }
}

那么，我们接口里的字段如果进行标注呢，比如我们的参数是一个对象的话，我们可以在对象的字段上进行标注，如果不是的话，可以直接在路由的方法上进行标注。如下:
@ApiModel 表示这是一个 Api 对象，@ApiModelProperty 表示这个字段的名称

@ApiModel
public class AddParams {
    /**
     * 账号
     */
    @ApiModelProperty("账号")
    private String account;
    /**
     * 密码
     */
    @ApiModelProperty("密码")
    private String password;
}