推薦一個軟體自動生成介面文件（帶實現）

胖琪的升級之路發表於2019-03-13

Swagger2

上次給大家推薦Swagger2這個神器，自動生成介面文件。不需要自己再專門寫文件，對於程式設計師來說能提高工作效率。

但是上篇並沒有講怎麼使用Wagger2這個軟體，今天就帶大家實現下。

環境

使用的語言是Java,其他語言也有型別的實現。官網連結:swagger2

框架是SpringBoot,構建工具是gradle.

實現

構建元件

在微服務開發中，我們會建立多個後端程式，在每個程式上都將swagger2的配置寫一遍，顯得很臃腫，我們這次在開發的時候將swagger2打造成一個元件的方式，後期直接引用。

新建立Gradle專案

// 增加依賴
dependencies {
    compile("io.springfox:springfox-swagger2:2.9.1")
    compile("io.springfox:springfox-swagger-ui:2.9.1")
    compile("org.springframework.boot:spring-boot-autoconfigure:1.5.10.RELEASE")
    compileOnly("org.springframework.data:spring-data-commons:1.12.6.RELEASE")
}
複製程式碼

建立依賴的類


// 注意有些引數我們是通過配置檔案配置過來的
@Configuration
@EnableSwagger2
public class Swagger2 {

    @Resource
    SwaggerProperties swaggerProperties;

    /** 
     * 注入docket
     * @return: Docket 
     * @author: fruiqi
     * @date: 19-2-18 下午6:20
     */ 
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(createApiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage(swaggerProperties.getBasePacakge()))
                .paths(PathSelectors.any())
                .build();
    }

    /** 
     * 建立api 
     * @return: springfox.documentation.service.ApiInfo 
     * @author: fruiqi
     * @date: 19-2-18 下午6:20
     */ 
    private ApiInfo createApiInfo(){
        return new ApiInfoBuilder()
                .title(swaggerProperties.getTitle())
                .description(swaggerProperties.getDescription())
                .version(swaggerProperties.getVersion())
                .build();
    }


}

複製程式碼

讀取配置檔案的類

@Configuration
public class SwaggerProperties {

    /**
     * 標題 預設
     */
    @Value("${swagger.title}")
    private String title = "標題";

    /**
     * 描述
     */
    @Value("${swagger.description}")
    private String description = "描述";

    /**
     * 版本號
     */
    @Value("${swagger.version}")
    private String version = "1.0.0";

    /**
     * 包路徑資訊
     */
    @Value("${swagger.basepackage}")
    private String basePacakge = "com.infervision";

    public String getTitle() {
        return title;
    }

    public void setTitle(String title) {
        this.title = title;
    }

    public String getDescription() {
        return description;
    }

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

    public String getVersion() {
        return version;
    }

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

    public String getBasePacakge() {
        return basePacakge;
    }

    public void setBasePacakge(String basePacakge) {
        this.basePacakge = basePacakge;
    }
}

複製程式碼

我們的檔案屬性放到配置檔案中，作為元件內容引入到別的專案中，配置檔案類中使用的屬性從其他專案配置檔案獲取。


其他專案引入上面的wagger元件，元件的專案名稱
compile project(':swagger-manage')

//配置檔案如下
swagger:
  title: test
  description: 開發devapi
  version: 1.0.0
  basepackage: com.infervision
複製程式碼

我們在其他專案可以隨意引入該元件，但更好的引入方式可以將其打成mavenjar包，放到maven倉庫中，以後可以使用maven的方式呼叫自己生成的swagger元件。

使用

建立Controller類，使用不同的註解標識我們建立的介面。

@RestController
@RequestMapping("people")
@Api(value = "people", description = "使用者控制端")
public class PeopleController {

    /**
     * 日誌
     */
    private static final Logger logger = LoggerFactory.getLogger(PeopleController.class);

    @Autowired
    PeopleService peopleService;


    /**
     * 根據使用者實體內容 分類查詢使用者
     * 1. 在這裡 vo層將查詢條件封裝成為一個實體或者
     * 引數較少可以直接使用RESTful的方式將其傳參
     * @param people 使用者實體
     * @return: com.infervision.model.People
     * @author: fruiqi
     * @date: 19-2-20 上午10:45
     */
    @GetMapping
    @ApiOperation(value = "獲取使用者列表資訊", notes = "條件可以選擇 使用者名稱,公司等內容")
    public List<PeopleVo> getPeoples(PeopleVo people) throws CommonException {
        List<PeopleVo> peoples = peopleService.getPeoples(people);
        return peoples;
    }


    /**
     * 增加使用者資訊
     *
     * @param peopleVo 增加的使用者資訊
     * @return: com.infervision.model.PeopleVo
     * @author: fruiqi
     * @date: 19-2-20 下午3:31
     */
    @PostMapping
    @ApiOperation(value = "增加使用者")
    public PeopleVo addPeople(@RequestBody  PeopleVo peopleVo) {
        PeopleVo result = peopleService.addPeople(peopleVo);
        return result;
    }

    /**
     * 修改物件
     * @param id       使用者id
     * @param peopleVo 修改的物件
     * @return: com.infervision.model.PeopleVo
     * @author: fruiqi
     * @date: 19-2-20 下午4:06
     */
    @PutMapping("{id}")
    @ApiOperation(value="更新使用者")
    @ApiImplicitParams({
            @ApiImplicitParam(dataType = "string",name = "id",value = "使用者id",required = true)
    })
    public PeopleVo updatePeople(@PathVariable Integer id, @RequestBody PeopleVo peopleVo) {
        PeopleVo result = peopleService.updatePeople(id, peopleVo);
        return result;
    }


    @DeleteMapping("{id}")
    @ApiOperation(value="刪除使用者")
    @ApiImplicitParam(dataType = "string",name = "id",value = "使用者id",required = true)
    public void deletePeople(@PathVariable Integer id){

        if (id != null){
            peopleService.deletePeople(id);
            logger.info("[INFO]  刪除使用者id  ");
        }


    }


}

複製程式碼

成功示意圖

2019-03-13-22-58-09

總結

上面的實現方式我們就打造成一個wagger2的元件了，後期我們在使用就可以直接引入專案。

原始碼地址：https://github.com/menhuan/notes/tree/master/code/codebase-master/swagger-manage

可以直接獲取元件內容。

字尾內容

·END·

路雖遠，行則必至

本文原發於 同名微信公眾號「胖琪的升級之路」，回覆「1024」你懂得，給個讚唄。

微信ID：YoungRUIQ

公眾號

相關文章