原创 Springboot 从零开始 8 Swagger2生成API文档

简单的使用Swagger2的方式参考这个网址：
https://www.ibm.com/developerworks/cn/java/j-using-swagger-in-a-spring-boot-project/index.html

注意事项和使用技巧：
1.打开Swagger的页面时直接输入http://localhost/swagger-ui.html
2.通过@PostMapping()注解只保留一种访问接口的方式就不会在Swagger中出现GET/PUT/DELETE等其他同样的接口说明
3.在入参中给参数添加说明，例如入参是一个json对象，我们可以简单定义一个model并添加@ApiModelProperty(“描述”)注解对属性进行描述，model需要@ApiModel进行注释。在controller的对应接口中修改request param类型为定义的model，入参的时候json会自动解释成对应的model（已测试，不会说无法映射到自定义类）。后面附SwaggerUI的效果图，response同理，定义一个ResponseObject即可准确说明。

package eugene.project.eop.model;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;

@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
@ApiModel
public class RequestObject {

    @ApiModelProperty("页码")
    private int index;

    @ApiModelProperty("一页的数量")
    private int pageSize;

    @ApiModelProperty("属性1")
    private String property1;

    @ApiModelProperty("属性2")
    private String property2;

    @ApiModelProperty("属性3")
    private String property3;

}

	@RequiredToken
    @PostMapping("/projects")
    @ApiOperation("查询所有项目")
    public Map<String, Object>projects(@ApiParam(name = "请求体", value = "说明", required = true) @RequestBody RequestObject params) throws Exception {
        Map<String, Object> map = ETools.responseMap();
        EUser user = (EUser) RequestHolder.get("user");

        Integer index = params.getIndex();
        Integer pageSize = params.getPageSize();

        Sort sort = Sort.by(Sort.Direction.DESC, "id");
        PageRequest pageRequest = PageRequest.of(index, pageSize, sort);
        Page<EProject> page = projectRepository.findAllByUid(user.getId(), pageRequest);
        map.put("data", page);
        return map;
    }

4.Swagger可以配置自动参数用于测试（token），首先在Swagger配置类的docket增加配置.securitySchemes(securitySchemes())和.securityContexts(securityContexts())。它们的入参分别绑定相关的配置，最重要的是ApiKey就是我们需要配置的自动参数，它的初始化方法中，$1就是参数名，$2就是位置（还可以是cookie）

@Configuration
public class Swagger2Config {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("service")
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("eugene.project.eop.controller"))
                .paths(PathSelectors.any())
                .build()
                .securitySchemes(securitySchemes())
                .securityContexts(securityContexts());
    }

    private List<ApiKey> securitySchemes() {
        List<ApiKey> list = new ArrayList<ApiKey>();
        list.add(new ApiKey(HttpHeaders.AUTHORIZATION, "token", "header"));
        return list;
    }

    private List<SecurityContext> securityContexts() {
        List<SecurityContext> securityContexts=new ArrayList<>();
        securityContexts.add(
                SecurityContext.builder()
                        .securityReferences(defaultAuth())
//                        .forPaths(PathSelectors.regex("^(?!auth).*$"))//如果需要制定某个路径接口需要验证才添加测试参数
                        .build());
        return securityContexts;
    }

    List<SecurityReference> defaultAuth() {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        List<SecurityReference> securityReferences=new ArrayList<>();
        securityReferences.add(new SecurityReference("Authorization", authorizationScopes));
        return securityReferences;
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("EOP Switcher")
                .description("eugene's owned project")
                .version("0.0.1")
                .build();
    }

}

重启项目就可以看到SwaggerUI中可以添加的登录认证字段（Authorization这个字符串是可以修改成自己的描述的，HttpHeaders.AUTHORIZATION其实是一个字符串常量）

执行execute查看效果