swagger2 使用

springboot2.0 + swagger2 的使用，可以说把rest接口的文档梳理的更规范，也更便捷和更易维护了

swagger2 使用

对于配置文件的参数，我们习惯于配置到yanl 文件中

ronghe:
  # Swagger相关配置
  swagger:
    basePackage: com.longchuang.ronghe
    title: xxx
    description: xxxxx.
    version: 2.0
    author: sisyphus
    url: https://xxx
    email: [email protected]
    license: Apache 2.0
    licenseUrl: https://www.apache.org/licenses/LICENSE-2.0.html

@Data
public class SwaggerProperties {
    private String basePackage;
    private String title;
    private String description;
    private String version;
    private String author;
    private String url;
    private String email;
    private String license;
    private String licenseUrl;
}

yml 文件属性注入

@Data
@Component
@Configuration
@ConfigurationProperties(prefix = "ronghe")
public class SixsectorProperties {

    private SwaggerProperties swagger = new SwaggerProperties();
}

swagger 配置

@Configuration
@EnableSwagger2
public class SixsectorConfig {

    @Autowired
    private SixsectorProperties properties;
    @Autowired
    private PersonProperties personProperties;
    @Autowired
    RedisService redisService;
    @Autowired
    private ObjectMapper mapper;
    @Autowired
    UserService userService;

    @Bean
    public Docket swaggerApi() throws RedisConnectException, JsonProcessingException {
        SwaggerProperties swagger = properties.getSwagger();
        PersonTest personTest = personProperties.getPersonTest();

        //权限
        ParameterBuilder ticketPar = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<Parameter>();
        ticketPar.name("Authentication").description("认证token")
                .modelRef(new ModelRef("string"))
                .parameterType("header").defaultValue(getToken()) // 设置默认权限为超级管理员
                .required(false).build(); //header中的ticket参数非必填，传空也可以
        pars.add(ticketPar.build());    //根据每个方法名也知道当前方法在设置什么参数

        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage(swagger.getBasePackage()))
                .paths(PathSelectors.any())
                .build()
                .globalOperationParameters(pars)  // 这边如果不配置权限可省略
                .apiInfo(apiInfo(swagger));
    }

    private ApiInfo apiInfo(SwaggerProperties swagger) {
        return new ApiInfo(
                swagger.getTitle(),
                swagger.getDescription(),
                swagger.getVersion(),
                null,
                new Contact(swagger.getAuthor(), swagger.getUrl(), swagger.getEmail()),
                swagger.getLicense(), swagger.getLicenseUrl(), Collections.emptyList());
    }

    /**
     * 仅用于swagger auth请求（这个方法看各位获取token的方式了，不可模仿。主要参考各系统的login接口）
     * @return
     */
    public String getToken() throws RedisConnectException, JsonProcessingException {
        String token = SixsectorUtil.encryptToken(JWTUtil.sign("sixsector", "211a547a512e09ad375c48540560f4df"));
        LocalDateTime expireTime = LocalDateTime.now().plusSeconds(properties.getShiro().getJwtTimeOut());
        String expireTimeStr = DateUtil.formatFullTime(expireTime);

        User user = userService.findByName("sixsector");

        // zset 存储登录用户，score 为过期时间戳
        this.redisService.zadd(SixsectorConstant.ACTIVE_USERS_ZSET_PREFIX, Double.valueOf(expireTimeStr), mapper.writeValueAsString(user));
        // redis 中存储这个加密 token，key = 前缀 + 加密 token + .ip
        this.redisService.set(SixsectorConstant.TOKEN_CACHE_PREFIX + token + StringPool.DOT + "127.0.0.1", token, properties.getShiro().getJwtTimeOut() * 1000);

        return token;
    }

如何使用？
在接口上面使用

    @ApiOperation(value = "查询地区数据",notes = "查询数据参数,支持条件查询传入参数name",httpMethod = "GET")

访问路径：
http://localhost:7766/swagger-ui.html