swagger介绍

swagger是一个文档生成的框架，可以通过简单的json或者yaml语言生成规范、美观的后端接口文档，文档可以支持直接输入数据进行接口测试。在开发Restful风格的应用时后端可以采用此框架来降低与前端的沟通成本。在工期紧时也可以使用swagger来代替单元测试【下下策，如果可以写单元测试的话还是单元测试更好一点，因为单元测试可复现，swagger尤其是复杂的业务，测试的多了输入用的json数据都乱了】

swagger+Spring配置

maven引入

<swagger.version>2.7.0</swagger.version>


<profile>
 <id>development</id>
 <properties>
   <profiles.active>development</profiles.active>
 </properties>
 <dependencies>
   <dependency>
           <groupId>io.springfox</groupId>
           <artifactId>springfox-swagger2</artifactId>
           <version>${swagger.version}</version>
       </dependency>

       <dependency>
           <groupId>io.springfox</groupId>
           <artifactId>springfox-swagger-ui</artifactId>
           <version>${swagger.version}</version>
       </dependency>
 </dependencies>
</profile>

配置swagger属性

@Configuration
@EnableSwagger2
public class Swagger2 {
    @Value("${swagger2.description.title}")
    private String title;
    @Value("${swagger2.description.description}")
    private String description;
    @Value("${swagger2.description.serviceUrl}")
    private String serviceUrl;
    @Value("${swagger2.description.contact}")
    private String contact;
    @Value("${swagger2.description.version}")
    private String version;

    @Value("${swagger2.pathRegex}")
    private String swaggerPathRegex;

    @Bean
    public Docket api() {
        return (new Docket(DocumentationType.SWAGGER_2))
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.regex(this.swaggerPathRegex))
                .build()
                .apiInfo(this.apiInfo());
    }

    private ApiInfo apiInfo() {
        return (new ApiInfoBuilder())
                .title(this.title)
                .description(this.description)
                .version(this.version)
                .termsOfServiceUrl(String.format("http://%s", this.serviceUrl))
                .license("LICENSE")
                .licenseUrl(this.serviceUrl)
                .build();
    }

}

最好把变量都写到配置文件里，当然你也可以在代码里写死，看个人习惯吧，这个可以支持markdown的，可以自己该插入表格就表格、该加粗加粗，该倾斜倾斜............

在接口类做标注

@Controller
@Api(value = "/api/Local/mapping", description = "本地映射管理", tags = "Local Mapping")
@RequestMapping("/api/Local/mapping")
@ResponseBody
public class MappingController {

    @Resource
    private MappingService mappingService;

    @ApiOperation("获得所有可用映射的列表")
    @RequestMapping(value = "/getAll", method = RequestMethod.GET)
    public ResponseWrapper<List<MappingVO>> getAllMappings() {
        return mappingService.getAllMappings();
    }

    @ApiOperation("获得指定映射的信息")
    @RequestMapping(value = "/{mappingId}", method = RequestMethod.GET)
    public ResponseWrapper<MappingVO> getMapping(@PathVariable Integer mappingId) {
        return mappingService.getMapping(mappingId);
    }

    @ApiOperation("激活对应映射")
    @RequestMapping(value = "/activation/{mappingId}", method = RequestMethod.POST)
    public ResponseWrapper<Boolean> activeMapping(@PathVariable Integer mappingId) {
        return mappingService.activeMapping(mappingId);
    }

    @ApiOperation("关闭对应映射")
    @RequestMapping(value = "/inactivation/{mappingId}", method = RequestMethod.POST)
    public ResponseWrapper<Boolean> inactiveMapping(@PathVariable Integer mappingId) {
        return mappingService.inactiveMapping(mappingId);
    }

    @ApiOperation("添加新映射")
    @RequestMapping(value = "/add", method = RequestMethod.POST)
    public ResponseWrapper<MappingVO> addNewMapping(@RequestBody MappingSubmit mappingSubmit) {
        return mappingService.addMapping(mappingSubmit);
    }

    @ApiOperation("删除对应映射")
    @RequestMapping(value = "/delete/{mappingId}", method = RequestMethod.DELETE)
    public ResponseWrapper<Boolean> removeMapping(@PathVariable Integer mappingId) {
        return mappingService.removeMapping(mappingId);
    }

    @ApiOperation("修改映射")
    @RequestMapping(value = "/{mappingId}", method = RequestMethod.PUT)
    public ResponseWrapper<Boolean> modifyMapping(@PathVariable Integer mappingId,@RequestBody MappingSubmit mappingSubmit) {
        return mappingService.modifyMapping(mappingId,mappingSubmit);
    }


}

在和前端有交互的数据类中做标注

public class LicenseServerVO {

    @ApiModelProperty("证书服务器id")
    private Integer id;

    @ApiModelProperty("证书服务器名称")
    private String name;

    @ApiModelProperty("证书服务器版本")
    private String version;

    @ApiModelProperty("证书适用的软件版本")
    private String adaption;

    @ApiModelProperty("备注")
    private String description;

    @ApiModelProperty("是否激活")
    private Boolean ifActive;

    public Integer getId() {
        return id;
    }

    public void setId(Integer id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getVersion() {
        return version;
    }

    public void setVersion(String version) {
        this.version = version;
    }

    public String getAdaption() {
        return adaption;
    }

    public void setAdaption(String adaption) {
        this.adaption = adaption;
    }

    public String getDescription() {
        return description;
    }

    public void setDescription(String description) {
        this.description = description;
    }

    public Boolean getIfActive() {
        return ifActive;
    }

    public void setIfActive(Boolean ifActive) {
        this.ifActive = ifActive;
    }

    public LicenseServerVO() {
    }

    public LicenseServerVO(Integer id, String name, String version, String adaption, String description, Boolean ifActive) {
        this.id = id;
        this.name = name;
        this.version = version;
        this.adaption = adaption;
        this.description = description;
        this.ifActive = ifActive;
    }
}

访问

启动项目，访问：http://serverName:portNumber/contextPath/swagger-ui.html即可

效果如下：

1.png 2.png